Condividi tramite

Informazioni sui controlli List-View

  • Articolo

Consulta l'esempio di controllo listview virtuale.

Un controllo di visualizzazione elenco è una finestra che visualizza un insieme di elementi. I controlli visualizzazione elenco offrono diversi modi per disporre e visualizzare gli elementi e sono molto più flessibili rispetto a semplici caselle di riepilogo . Ad esempio, è possibile visualizzare informazioni aggiuntive su ogni elemento nelle colonne a destra dell'icona e dell'etichetta.

List-View Stili e Viste

I controlli visualizzazione elenco possono visualizzare elementi in cinque visualizzazioni diverse. Lo stile della finestra del controllo specifica la visualizzazione predefinita. Gli stili di finestra aggiuntivi specificano l'allineamento degli elementi e delle funzionalità specifiche del controllo. Nella tabella seguente sono descritte le visualizzazioni.

Nome visualizzazione Descrizione
Visualizzazione icona Specificato dallo stile della finestra LVS_ICON o passando LV_VIEW_ICON con il messaggio LVM_SETVIEW. Ogni elemento viene visualizzato come icona a dimensione intera con un'etichetta sotto di essa. L'utente può trascinare gli elementi in qualsiasi posizione nella finestra della visualizzazione elenco.
Visualizzazione icona piccola Specificato dallo stile della finestra LVS_SMALLICON o passando LV_VIEW_SMALLICON con LVM_SETVIEW. Ogni elemento viene visualizzato come icona piccola con l'etichetta a destra di esso. L'utente può trascinare gli elementi in qualsiasi posizione.
Visualizzazione elenco Specificato dallo stile della finestra LVS_LIST o passando LV_VIEW_LIST con LVM_SETVIEW. Ogni elemento viene visualizzato come icona piccola con un'etichetta a destra di esso. Gli elementi sono disposti in colonne e l'utente non può trascinarli in una posizione arbitraria.
La visualizzazione del report (dettagli) Specificato dallo stile della finestra LVS_REPORT o tramite il passaggio di LV_VIEW_DETAILS insieme a LVM_SETVIEW. Ogni elemento viene visualizzato sulla propria riga, con informazioni disposte in colonne. La colonna all'estrema sinistra è sempre giustificata e contiene l'icona e l'etichetta piccole. Le colonne successive contengono elementi secondari come specificato dall'applicazione. Ogni colonna ha un'intestazione, a meno che non si specifichi anche lo stile della finestra LVS_NOCOLUMNHEADER.
Visualizzazione riquadro Versione 6 e successive. È specificato passando LV_VIEW_TILE con LVM_SETVIEW. Ogni elemento viene visualizzato come icona a dimensione intera con un'etichetta di una o più righe accanto a essa.

 

Le schermate seguenti usano visualizzazioni per mostrare diverse quantità di informazioni su ognuno di sette animali domestici. Le visualizzazioni illustrano come visualizzare le informazioni in Windows Vista. Gli stili di visualizzazione per il controllo sono stati impostati sul tema "Explorer" usando SetWindowTheme.

La schermata seguente mostra la visualizzazione dei dettagli.

schermata che mostra le informazioni in cinque colonne e sette righe

La schermata seguente mostra la visualizzazione icona.

screenshot che mostra solo il nome di ogni animale domestico e un'icona che indica la specie

La schermata seguente mostra la visualizzazione elenco.

screenshot che mostra, per ogni animale domestico, un'icona grande accanto al testo del nome, della razza e del prezzo dell'animale domestico

La schermata seguente mostra la vista a riquadri.

visualizzazione riquadro.

È possibile modificare il tipo di visualizzazione dopo aver creato un controllo visualizzazione elenco. Per recuperare e modificare lo stile della finestra, usare le funzioni GetWindowLong e SetWindowLong. Per determinare gli stili di finestra della visualizzazione corrente, usare il valore LVS_TYPEMASK.

È possibile controllare la disposizione degli elementi nella visualizzazione icona o icona piccola specificando lo stile LVS_ALIGNTOP (impostazione predefinita) o LVS_ALIGNLEFT finestra.

È possibile modificare l'allineamento dopo aver creato un controllo visualizzazione elenco. Per determinare l'allineamento corrente, usare il valore LVS_ALIGNMASK.

Altri stili di finestra offrono altre opzioni, ad esempio se un utente può modificare le etichette o selezionare più elementi alla volta. Per un elenco completo, vedere List-View Stili della finestra.

Stili di List-View estesi

Gli stili di controllo della visualizzazione elenco estesi offrono opzioni come caselle di controllo, barre di scorrimento piatte, linee della griglia e rilevamento dinamico. Per un elenco completo, vedere List-View Stili Estesi. Non è possibile accedere agli stili di visualizzazione elenco estesi nello stesso modo degli stili di finestra standard. Non si usano le funzioni di GetWindowLong e SetWindowLong per apportare modifiche di stile estese.

Sono presenti due messaggi che impostano e recuperano informazioni sullo stile esteso, LVM_SETEXTENDEDLISTVIEWSTYLE e LVM_GETEXTENDEDLISTVIEWSTYLE. Anziché inviare i messaggi in modo esplicito, è possibile usare le macro corrispondenti seguenti: ListView_SetExtendedListViewStyle, ListView_SetExtendedListViewStyleExe ListView_GetExtendedListViewStyle.

Stile List-View virtuale

Una visualizzazione elenco virtuale è un controllo visualizzazione elenco con lo stile LVS_OWNERDATA. Questo stile consente al controllo di gestire milioni di elementi perché il compito di gestire i dati degli elementi ricade sul proprietario. In questo modo è possibile usare il controllo visualizzazione elenco virtuale con database di informazioni di grandi dimensioni, in cui sono già presenti metodi specifici di accesso ai dati.

Un controllo di visualizzazione dell'elenco virtuale mantiene di per sé pochissime informazioni sugli elementi. Fatta eccezione per la selezione degli elementi e le informazioni sul focus, il proprietario del controllo deve gestire tutte le informazioni sugli elementi. Altri processi richiedono informazioni sull'elemento dal proprietario usando LVN_GETDISPINFO codici di notifica.

Poiché questo tipo di controllo elenco è destinato a set di dati di grandi dimensioni, è consigliabile memorizzare nella cache i dati degli elementi richiesti per migliorare le prestazioni di recupero. La visualizzazione elenco fornisce un meccanismo di suggerimento per la cache per facilitare l'ottimizzazione della cache. L'hint viene implementato sotto forma di codice di notifica LVN_ODCACHEHINT.

Creazione di un controllo List-View virtuale

È possibile creare controlli della visualizzazione elenco virtuale usando la funzione CreateWindow o CreateWindowEx, specificando lo stile della finestra LVS_OWNERDATA come parte del parametro della funzione dwStyle. Il passaggio dinamico da e verso lo stile di LVS_OWNERDATA non è supportato.

È possibile utilizzare lo stile LVS_OWNERDATA in combinazione con la maggior parte degli altri stili di finestra, ad eccezione dello stile LVS_SORTASCENDING o LVS_SORTDESCENDING. Per impostazione predefinita, tutti i controlli della visualizzazione elenco virtuale hanno lo stile di LVS_AUTOARRANGE.

Per consentire la visualizzazione degli elementi nell'elenco, è prima necessario inviare il messaggio di LVM_SETITEMCOUNT in modo esplicito o tramite la macro ListView_SetItemCountEx.

I messaggi seguenti non sono supportati nello stile di LVS_OWNERDATA: LVM_ENABLEGROUPVIEW, LVM_GETITEMTEXT, LVM_SETTILEINFOe LVM_MAPIDTOINDEX.

Problemi di compatibilità

Tutti e quattro gli stili di visualizzazione elenco—icona, icona piccola, elenco e visualizzazione report—supportano lo stile LVS_OWNERDATA. I controlli visualizzazione elenco con lo stile LVS_OWNERDATA non archivia informazioni specifiche dell'elemento. Di conseguenza, gli unici flag di stato dell'elemento validi che è possibile applicare a un elemento sono LVIS_SELECTED e LVIS_FOCUSED. Nessun'altra informazione sullo stato viene archiviata. In particolare, il controllo visualizzazione elenco non mantiene immagini di stato o sovrapposizione per ogni elemento. Tuttavia, è possibile fare in modo che il controllo visualizzazione elenco esegua una query alla tua applicazione per ottenere queste immagini inviando un messaggio di LVM_SETCALLBACKMASK.

La maggior parte dei messaggi di controllo della visualizzazione elenco e delle macro associate è completamente supportata. Tuttavia, alcuni messaggi presentano limitazioni o non sono supportati quando si usa lo stile di LVS_OWNERDATA. Nella tabella seguente vengono riepilogati i messaggi interessati.

Messaggio Limitazione
LVM_ARRANGE Non supporta lo stile LVA_SNAPTOGRID.
LVM_DELETEALLITEMS Imposta il conteggio degli elementi su zero e cancella tutte le variabili di selezione interne, ma in realtà non elimina alcun elemento. Esegue una chiamata di ritorno per la notifica.
LVM_DELETEITEM È supportato solo per l'integrità della selezione e non elimina effettivamente un elemento.
LVM_GETITEMSTATE Restituisce solo gli stati di focus e di selezione, ovvero gli stati archiviati dal controllo visualizzazione elenco.
LVM_GETNEXTITEM Non supporta i criteri di ricerca per la visualizzazione in elenco come LVNI_CUT, LVNI_HIDDENo LVNI_DROPHILITED. Sono supportati tutti gli altri criteri.
LVM_GETWORKAREAS Non è supportato.
LVM_INSERTITEM È supportato solo per l'integrità della selezione.
LVM_SETITEM Non è supportato. Per impostare lo stato dell'elemento, usare il messaggio ListView_SetItemState.
LVM_SETITEMCOUNT Imposta il numero di elementi attualmente presenti nell'elenco. Se il controllo della visualizzazione elenco invia una notifica che richiede dati per qualsiasi elemento fino al valore massimo impostato, il proprietario deve essere pronto a fornire tali dati. I parametri del messaggio supportano i controlli di visualizzazione della lista virtuale.
LVM_SETITEMPOSITION Non è supportato.
LVM_SETITEMSTATE Consente unicamente la modifica degli stati di selezione e di focus per l'elemento.
LVM_SETITEMTEXT Non è supportato. È responsabilità dell'applicazione mantenere i testi dell'articolo.
LVM_SETWORKAREAS Non è supportato.
LVM_SORTITEMS Non è supportato. È responsabilità dell'applicazione presentare gli elementi nell'ordine desiderato.

 

Gestione dei codici di notifica di controllo virtuale List-View

I controlli visualizzazione elenco con lo stile di LVS_OWNERDATA inviano gli stessi codici di notifica degli altri controlli visualizzazione elenco e due controlli aggiuntivi: LVN_ODCACHEHINT e LVN_ODFINDITEM. Di seguito sono riportate le notifiche più comuni inviate dal controllo visualizzazione elenco con lo stile LVS_OWNERDATA.

Notifica Descrizione
LVN_GETDISPINFO Un controllo visualizzazione elenco virtuale gestisce autonomamente pochissime informazioni sugli elementi. Di conseguenza, spesso invia il codice di notifica LVN_GETDISPINFO per richiedere informazioni sull'elemento. Questo messaggio viene gestito in modo analogo agli elementi di callback in un controllo elenco standard. Poiché il numero di elementi supportati dal controllo può essere molto grande, la memorizzazione nella cache dei dati degli elementi migliora le prestazioni. Quando si gestisce LVN_GETDISPINFO, il proprietario del controllo tenta innanzitutto di fornire informazioni sull'elemento richiesto dalla cache. Per altre informazioni, vedere Gestione cache. Se l'elemento richiesto non viene memorizzato nella cache, il proprietario deve essere preparato per fornire le informazioni tramite altri mezzi.
LVN_ODCACHEHINT Una visualizzazione elenco virtuale invia il codice di notifica LVN_ODCACHEHINT per facilitare l'ottimizzazione della cache. Il codice di notifica fornisce valori di indice inclusivo per un intervallo di elementi che consiglia di memorizzare nella cache. Dopo aver ricevuto il codice di notifica, il proprietario deve essere preparato a caricare la cache con informazioni sull'elemento per l'intervallo richiesto in modo che le informazioni saranno immediatamente disponibili quando viene inviato un messaggio di LVN_GETDISPINFO.
LVN_ODFINDITEM Il codice di notifica LVN_ODFINDITEM viene inviato da un controllo di visualizzazione elenco virtuale quando il controllo richiede al proprietario di trovare un particolare elemento di callback. Il codice di notifica viene inviato quando il controllo visualizzazione elenco riceve l'accesso rapido tramite chiave o quando riceve un messaggio di LVM_FINDITEM. Le informazioni di ricerca vengono inviate sotto forma di una struttura LVFINDINFO, che è un membro della struttura NMLVFINDITEM. Il proprietario deve essere pronto a cercare un elemento che corrisponda alle informazioni fornite dal controllo dell'elenco. Il proprietario restituisce l'indice dell'elemento se ha esito positivo o -1 se non viene trovato alcun elemento corrispondente.

 

Gestione cache

Un controllo visualizzazione elenco con lo stile LVS_OWNERDATA produce un numero elevato di codici di notifica LVN_GETDISPINFO e, per facilitare l'ottimizzazione della cache, un messaggio LVN_ODCACHEHINT. LVN_ODCACHEHINT i messaggi forniscono informazioni sugli elementi consigliati da includere nella cache. Questi messaggi vengono inviati come messaggi di WM_NOTIFY, con il valore lParam che funge da indirizzo di una struttura di NMLVCACHEHINT.

La struttura NMLVCACHEHINT include due membri interi, iFrom e iTo, che rappresentano gli endpoint inclusivi di un intervallo di elementi che probabilmente saranno necessari. Il proprietario deve essere preparato per caricare la cache con le informazioni sull'elemento per ognuno degli elementi all'interno dell'intervallo consigliato.

Il controllo elenco richiede spesso informazioni sugli elementi per il primo elemento (offset 0). Il codice di notifica LVN_ODCACHEHINT potrebbe non includere sempre l'elemento 0, ma deve essere sempre incluso nella cache.

Gli ultimi elementi dell'elenco sono spesso accessibili. Pertanto, il proprietario potrebbe voler mantenere una seconda cache che includa gli elementi alla fine dell'elenco. L'intervallo richiesto da LVN_ODCACHEHINT può essere controllato rispetto alla cache finale per renderlo disponibile automaticamente anziché ricaricare lo stesso intervallo di fine ogni volta.

List-View aree di lavoro

I controlli visualizzazione elenco supportano le aree di lavoro, ovvero aree virtuali rettangolari usate dal controllo visualizzazione elenco per disporre gli elementi. Un'area di lavoro non è una finestra e non può avere un bordo visibile. Per impostazione predefinita, il controllo visualizzazione elenco non dispone di aree di lavoro. Creando un'area di lavoro, è possibile creare un bordo vuoto a sinistra, in alto o a destra degli elementi oppure fare in modo che una barra di scorrimento orizzontale venga visualizzata quando normalmente non ne esiste una.

Quando viene creata un'area di lavoro, gli elementi che si trovano all'interno dell'area di lavoro diventano membri dell'area di lavoro. Analogamente, se un elemento viene spostato in un'area di lavoro, l'elemento diventa un membro dell'area di lavoro. Se un elemento non si trova all'interno di un'area di lavoro, diventa automaticamente un membro della prima area di lavoro (indice 0). Per inserire un nuovo elemento all'interno di un'area di lavoro specifica, è prima necessario creare l'elemento e quindi usare il LVM_SETITEMPOSITION o il messaggio LVM_SETITEMPOSITION32 per spostarlo nell'area di lavoro desiderata.

La figura seguente è un esempio di un controllo visualizzazione elenco che contiene quattro aree di lavoro, ognuna in un quadrante diverso dell'area client.

schermata di un controllo di visualizzazione elenco con un'area di lavoro in ogni quadrante dell'area del client

È possibile usare più aree di lavoro per creare aree diverse all'interno di una visualizzazione. È possibile creare aree in una singola visualizzazione con significati diversi. Ad esempio, una visualizzazione di un file system potrebbe avere un'area per i file di lettura/scrittura e un'altra area per i file di sola lettura. L'utente può classificare gli elementi inserendoli in aree di lavoro diverse. Se un file viene spostato nell'area di sola lettura, diventerà di sola lettura.

Più aree di lavoro possono intersecarsi, ma tutti gli elementi che si trovano all'interno dell'intersezione diventano membri dell'area con l'indice inferiore; pertanto, è meglio evitare questa situazione. Quando si ordinano più aree di lavoro, gli elementi vengono ordinati rispetto agli altri elementi nella stessa area di lavoro.

Il numero di aree di lavoro può essere recuperato con il messaggio di LVM_GETNUMBEROFWORKAREAS. Le aree di lavoro vengono modificate con il messaggio LVM_SETWORKAREAS e possono essere recuperate con il messaggio LVM_GETWORKAREAS. Entrambi questi messaggi accettano l'indirizzo di una matrice di struttureRECTcome lParam e il numero di strutture RECT come wParam. I membri sinistro sinistro e superiore di queste strutture specificano le coordinate dell'angolo superiore sinistro (origine) dell'area di lavoro e il destro e membri inferiore specificano l'angolo inferiore destro dell'area di lavoro. Tutte le coordinate si trovano nelle coordinate client della visualizzazione elenco. Il numero massimo di aree di lavoro consentite è definito dal valore LV_MAX_WORKAREAS.

La modifica dell'area di lavoro non ha alcun effetto sui controlli visualizzazione elenco con la visualizzazione LVS_LIST o LVS_REPORT, ma le aree di lavoro verranno mantenute quando viene modificato il tipo di visualizzazione. Con le visualizzazioni LVS_ICON e LVS_SMALLICON, l'area di lavoro può essere modificata per modificare la modalità di visualizzazione degli elementi. La larghezza dell'area di lavoro (da destra a sinistra) che supera la larghezza del client del controllo causa l'impacchettamento degli elementi a quella larghezza e la visualizzazione della barra di scorrimento orizzontale. Rendendo più stretta la larghezza dell'area di lavoro rispetto alla larghezza dell'area client del controllo, gli elementi verranno racchiusi all'interno dell'area di lavoro e non nell'area client. Impostando il sinistro o membro superiore su un valore positivo, gli elementi verranno visualizzati a partire dall'area di lavoro, creando uno spazio vuoto tra il bordo del controllo e gli elementi. È anche possibile creare uno spazio vuoto tra il bordo destro del controllo e gli elementi rendendo la larghezza dell'area di lavoro inferiore alla larghezza del client del controllo.

elenchi di immagini List-View

Per impostazione predefinita, un controllo visualizzazione elenco non visualizza immagini di elementi. Per visualizzare le immagini degli elementi, è necessario creare elenchi di immagini e associarli al controllo . Un controllo visualizzazione elenco può avere tre elenchi di immagini:

  • Elenco di immagini che contiene icone a dimensione intera visualizzate quando il controllo è in visualizzazione icona.
  • Elenco di immagini che contiene icone di piccole dimensioni visualizzate quando il controllo è in visualizzazione icona piccola, visualizzazione elenco o visualizzazione report.
  • Un elenco di immagini che contiene immagini di stato, visualizzate a sinistra dell'icona grande o piccola. È possibile usare immagini di stato, ad esempio caselle di controllo selezionate e deselezionate, per indicare gli stati degli elementi definiti dall'applicazione. Le immagini di stato vengono visualizzate nella visualizzazione icona, nella visualizzazione icona piccola, nella visualizzazione elenco e nella visualizzazione report.

Gli elenchi di immagini a icona di dimensioni complete e piccole possono anche contenere immagini sovrapposte, progettate per essere disegnate in modo trasparente sulle icone degli elementi.

Per usare immagini sovrapposte in un controllo visualizzazione elenco:

  1. Chiamare la funzione ImageList_SetOverlayImage per assegnare un indice di immagine di sovrimpressione a un'immagine negli elenchi di immagini a icona di dimensioni intere e piccole. Un'immagine di sovrapposizione è identificata da un indice a base uno.
  2. È possibile associare un indice di immagine di sovrimpressione a un elemento quando si chiama la macro ListView_InsertItem o ListView_SetItem. Utilizzare la macro INDEXTOOVERLAYMASK per specificare un indice dell'immagine di sovrapposizione nel membro dello stato della struttura LVITEM dell'elemento. È inoltre necessario impostare i bit di LVIS_OVERLAYMASK nel membro stateMask .

Se viene specificato un elenco di immagini di stato, un controllo visualizzazione elenco riserva spazio a sinistra dell'icona di ogni elemento per un'immagine di stato.

Per associare un'immagine di stato a un elemento, utilizzare la macro INDEXTOSTATEIMAGEMASK per specificare un indice di immagine di stato nel membro dello stato della struttura LVITEM. L'indice identifica un'immagine nell'elenco di immagini di stato del controllo. Anche se gli indici dell'elenco di immagini sono in base zero, il controllo usa indici basati su un solo per identificare le immagini di stato. Un indice di immagine di stato pari a zero indica che un elemento non ha un'immagine di stato.

Per impostazione predefinita, quando un controllo visualizzazione elenco viene eliminato definitivamente, elimina definitivamente gli elenchi di immagini assegnati. Tuttavia, se un controllo visualizzazione elenco ha lo stile della finestra LVS_SHAREIMAGELISTS, l'applicazione è responsabile dell'eliminazione degli elenchi di immagini quando non sono più in uso. È necessario specificare questo stile se si assegnano gli stessi elenchi di immagini a più controlli di visualizzazione elenco; in caso contrario, più controlli potrebbero tentare di eliminare definitivamente lo stesso elenco di immagini.

List-View Elementi e sottoelementi

Ogni elemento in un controllo visualizzazione elenco ha un'icona, un'etichetta, uno stato corrente e un valore definito dall'applicazione. Usando i messaggi di visualizzazione elenco, è possibile aggiungere, modificare ed eliminare elementi, nonché recuperare informazioni sugli elementi.

Ogni elemento può avere uno o più elementi secondari . Un elemento secondario è una stringa che, nella visualizzazione report, viene visualizzata in una colonna separata dall'icona e dall'etichetta dell'elemento. Per specificare il testo di un elemento secondario, utilizzare il LVM_SETITEMTEXT o LVM_SETITEM messaggio. Tutti gli elementi di un controllo visualizzazione elenco hanno lo stesso numero di elementi secondari. Il numero di elementi secondari è determinato dal numero di colonne nel controllo visualizzazione elenco. Quando si aggiunge una colonna a un controllo visualizzazione elenco, si specifica l'indice dell'elemento secondario associato.

La struttura LVITEM definisce un elemento o un sottoelemento della visualizzazione elenco. Il membro iItem è l'indice a base zero dell'elemento. Il membro iSubItem è l'indice a partire da uno di un subelemento o zero se la struttura contiene informazioni su un elemento. Membri aggiuntivi specificano il testo, l'icona, lo stato e i dati dell'elemento. Dati elemento è un valore definito dall'applicazione associato a un elemento della visualizzazione a elenco.

Per aggiungere un elemento a un controllo visualizzazione elenco, utilizzare il messaggio LVM_INSERTITEM, specificando l'indirizzo di una strutturaLVITEM. Prima di aggiungere più elementi, è possibile inviare il controllo un messaggio LVM_SETITEMCOUNT, specificando il numero di elementi che il controllo conterrà. Questo messaggio consente al controllo di visualizzazione elenco di riallocare le relative strutture di dati interne una sola volta anziché ogni volta che si aggiunge un elemento. È possibile determinare il numero di elementi in un controllo visualizzazione elenco usando il messaggio LVM_GETITEMCOUNT. Se si aggiunge un numero elevato di elementi a un controllo visualizzazione elenco, è possibile velocizzare il processo disabilitando il ridisegno prima di aggiungere gli elementi, quindi abilitare il ridisegno dopo l'aggiunta degli elementi. Usare il messaggio WM_SETREDRAW per abilitare e disabilitare il ridisegno.

Per modificare gli attributi di un elemento della visualizzazione elenco, utilizzare il messaggio di LVM_SETITEM, specificando l'indirizzo di una strutturaLVITEM. Il membro mascherato della struttura specifica gli attributi dell'elemento che si desidera modificare. Ad esempio, per modificare solo il testo di un elemento o di un elemento secondario, usare il messaggio LVM_SETITEMTEXT.

Per recuperare informazioni su un elemento della vista elenco, utilizzare il messaggio LVM_GETITEM, specificando l'indirizzo della struttura LVITEM da riempire. Il membro della maschera di questa struttura specifica gli attributi dell'elemento da recuperare. Per recuperare solo il testo di un elemento o di un elemento secondario, usare il messaggio LVM_GETITEMTEXT.

Per eliminare un elemento della visualizzazione elenco, usare il messaggio LVM_DELETEITEM. È possibile eliminare tutti gli elementi in un controllo visualizzazione elenco usando il messaggio di LVM_DELETEALLITEMS.

List-View Stati Degli Elementi

Lo stato di un elemento è un valore che specifica la disponibilità dell'elemento, indica le azioni dell'utente o in caso contrario riflette lo stato dell'elemento. Un controllo visualizzazione elenco modifica alcuni bit di stato, ad esempio quando l'utente seleziona un elemento. Un'applicazione può modificare altri bit di stato per disabilitare o nascondere l'elemento o per specificare un'immagine di sovrimpressione o un'immagine dello stato. Per altre informazioni sulle immagini sovrapposte e sulle immagini di stato, vedere List-View Elenchi di immagini.

Lo stato di un elemento è specificato dal membro di stato della struttura LVITEM. Quando si specifica o si modifica lo stato di un elemento, il membro stateMask specifica quali bit di stato è necessario modificare. È possibile modificare lo stato di un elemento usando il messaggio di LVM_SETITEMSTATE. È possibile specificare lo stato di un elemento quando lo si crea o quando si modificano gli attributi usando il messaggio LVM_SETITEM. Per determinare lo stato corrente di un elemento, usare il messaggio LVM_GETITEMSTATE o LVM_GETITEM.

Per impostare l'immagine di sovrapposizione di un elemento, il membro stateMask della struttura LVITEM deve includere il valore LVIS_OVERLAYMASK e il membro state deve includere l'indice basato su uno dell'immagine di sovrapposizione, spostato a sinistra di 8 bit utilizzando la macro INDEXTOOVERLAYMASK. L'indice può essere zero per specificare nessuna immagine di sovrapposizione.

Per impostare l'immagine dello stato di un elemento, il membro stateMask della strutturaLVITEMdeve includere il valore LVIS_STATEIMAGEMASK e il membro stato deve includere l'indice in base uno dell'immagine di stato spostato a sinistra a 12 bit utilizzando la macro INDEXTOSTATEIMAGEMASK. L'indice può essere zero per specificare nessuna immagine di stato.

Elementi di Callback e Maschera di Callback

Per ciascuno dei suoi elementi, un controllo di visualizzazione elenco memorizza in genere il testo dell'etichetta, l'indice della lista di immagini delle icone dell'elemento e un insieme di flag di bit per lo stato dell'elemento. È possibile definire elementi di callback o modificare la maschera di callback del controllo per indicare che l'applicazione, anziché il controllo, archivia alcune o tutte queste informazioni. È possibile usare i callback se l'applicazione archivia alcune di queste informazioni.

Un elemento di callback in un controllo di visualizzazione elenco è un elemento per cui l'applicazione memorizza il testo, l'indice dell'icona o entrambi. È possibile definire gli elementi di callback quando si invia il messaggio di LVM_INSERTITEM per aggiungere un elemento al controllo visualizzazione elenco. Se l'applicazione archivia il testo per l'elemento o l'elemento secondario, impostare il membro pszText della struttura LVITEM dell'elemento su LPSTR_TEXTCALLBACK. Se l'applicazione archivia l'indice dell'icona per un elemento, impostare il membro iImage della struttura LVITEM dell'elemento su I_IMAGECALLBACK.

La maschera di callback in un controllo elenco è un insieme di flag di bit che specificano gli stati degli elementi per cui l'applicazione, anziché il controllo, archivia i dati attuali. La maschera di callback si applica a tutti gli elementi del controllo, a differenza della designazione dell'elemento di callback, che si applica a un elemento specifico. La maschera di callback è zero per impostazione predefinita, ovvero il controllo visualizzazione elenco archivia tutte le informazioni sullo stato dell'elemento. Dopo aver creato un controllo visualizzazione elenco e inizializzato gli elementi, è possibile inviare il messaggio LVM_SETCALLBACKMASK per modificare la maschera di callback. Per recuperare la maschera di callback corrente, inviare il messaggio di LVM_GETCALLBACKMASK.

Quando un controllo visualizzazione elenco deve visualizzare o ordinare un elemento della visualizzazione elenco per cui l'applicazione archivia le informazioni di callback, il controllo invia il codice di notifica LVN_GETDISPINFO alla finestra padre del controllo. Questo messaggio specifica una struttura NMLVDISPINFO che contiene il tipo di informazioni necessarie e identifica l'elemento o l'elemento secondario da recuperare. La finestra padre deve elaborare LVN_GETDISPINFO per fornire i dati richiesti.

Se il controllo visualizzazione elenco rileva una modifica nelle informazioni di callback di un elemento, ad esempio una modifica nel testo, nell'icona o nelle informazioni sullo stato, il controllo invia un codice di notifica LVN_SETDISPINFO per notificare la modifica.

Se si modificano gli attributi o i bit di stato di un elemento di callback, utilizzare il messaggio di LVM_UPDATE per forzare il controllo a ridipingere l'elemento. Questo messaggio determina inoltre la disposizione degli elementi del controllo se ha lo stile LVS_AUTOARRANGE. È possibile utilizzare il messaggio di LVM_REDRAWITEMS per ridisegnare un intervallo di elementi invalidando le parti corrispondenti dell'area client del controllo visualizzazione elenco.

Usando in modo efficace gli elementi di callback e la maschera di callback, è possibile assicurarsi che ogni attributo dell'elemento venga mantenuto in un'unica posizione. In questo modo è possibile semplificare l'applicazione, ma l'unico spazio salvato è la memoria che altrimenti sarebbe necessaria per archiviare le etichette degli elementi e il testo dell'elemento secondario.

List-View posizione dell'elemento

Ogni elemento della visualizzazione elenco ha una posizione e una dimensione, che è possibile recuperare e impostare usando i messaggi. È anche possibile determinare quale elemento, se disponibile, si trova in una posizione specificata. La posizione degli elementi della visualizzazione elenco è specificata in coordinate di visualizzazione, che sono coordinate client sovrapposte alla posizione di scorrimento.

Per recuperare e impostare la posizione di un elemento, usare i messaggi LVM_GETITEMPOSITION e LVM_SETITEMPOSITION. LVM_GETITEMPOSITION funziona per tutte le visualizzazioni, ma LVM_SETITEMPOSITION funziona solo per le visualizzazioni icona e icone di piccole dimensioni.

È possibile determinare quale elemento, se presente, si trova in una determinata posizione usando il messaggio LVM_HITTEST.

Per recuperare il rettangolo di delimitazione per un elemento di elenco o solo per l'icona o l'etichetta, utilizzare il messaggio LVM_GETITEMRECT.

Disposizione, ordinamento e ricerca di elementi

È possibile usare i messaggi di visualizzazione elenco per disporre e ordinare gli elementi e per trovare gli elementi in base ai relativi attributi o posizioni. La disposizione di elementi riposiziona gli elementi da allineare su una griglia, ma gli indici degli elementi non cambiano. L'ordinamento modifica la sequenza di elementi (e gli indici corrispondenti) e quindi li riposiziona di conseguenza. È possibile disporre gli elementi solo in visualizzazioni icona e icona di piccole dimensioni, ma è possibile ordinare gli elementi in qualsiasi visualizzazione. Per trovare elementi, inviare messaggi di visualizzazione elenco che specificano una posizione o una proprietà dell'elemento.

Per disporre gli elementi, usare il messaggio LVM_ARRANGE. È possibile assicurarsi che gli elementi siano disposti sempre specificando lo stile della finestra LVS_AUTOARRANGE.

Per ordinare gli elementi, usare il messaggio LVM_SORTITEMS. Quando si esegue l'ordinamento usando questo messaggio, si specifica una funzione di callback definita dall'applicazione che il controllo visualizzazione elenco chiama per confrontare l'ordine relativo di due elementi. Il controllo passa alla funzione di confronto i dati dell'elemento associati a ognuno dei due elementi. I dati dell'elemento sono il valore specificato nella struttura lParam della strutturaLVITEM dell'elemento quando è stata inserita nell'elenco. Specificando i dati dell'elemento appropriati e fornendo una funzione di confronto appropriata, è possibile ordinare gli elementi in base all'etichetta, a qualsiasi elemento secondario o a qualsiasi altra proprietà. Si noti che l'ordinamento degli elementi non riordina gli elementi secondari corrispondenti. Quando gli elementi vengono riordinati, gli elementi secondari corrispondenti vengono trasportati con loro; cioè, le righe intere vengono tenute insieme. Per ordinare le colonne separatamente l'una dall'altra, scollegando gli elementi secondari dai relativi elementi, è necessario rigenerare le colonne dopo l'ordinamento utilizzando LVM_SETITEM.

È possibile assicurarsi che un controllo visualizzazione elenco sia sempre ordinato specificando lo stile della finestra LVS_SORTASCENDING o LVS_SORTDESCENDING. I controlli con questi stili usano il testo dell'etichetta degli elementi per ordinarli in ordine crescente o decrescente. Non è possibile fornire una funzione di confronto quando si usano questi stili di finestra. Se un controllo di visualizzazione elenco ha uno di questi stili, un messaggio LVM_INSERTITEM fallirà se si tenta di inserire un elemento che ha LPSTR_TEXTCALLBACK come valore per il membro pszText della sua struttura LVITEM.

È possibile trovare un elemento della visualizzazione elenco con proprietà specifiche usando il messaggio LVM_FINDITEM. È possibile trovare un elemento della visualizzazione elenco che si trova in uno stato specificato e ha una relazione specificata con un determinato elemento usando il messaggio LVM_GETNEXTITEM. Ad esempio, è possibile recuperare l'elemento selezionato successivo a destra di un elemento specificato.

colonne List-View

Le colonne controllano il modo in cui gli elementi e i relativi elementi secondari vengono visualizzati nella visualizzazione report. Ogni colonna ha un titolo e una larghezza ed è associata a un elemento secondario specifico; l'elemento secondario zero è l'icona e l'etichetta dell'elemento. Gli attributi di una colonna sono definiti da una strutturaLVCOLUMN.

Per aggiungere una colonna a un controllo visualizzazione elenco, utilizzare il messaggio LVM_INSERTCOLUMN. Per eliminare una colonna, usare il messaggio LVM_DELETECOLUMN.

Nota

L'eliminazione della colonna zero di un controllo visualizzazione elenco è supportata solo in ComCtl32.dll versione 6 e successive. La versione 5 supporta anche l'eliminazione della colonna zero, ma solo dopo aver usato CCM_SETVERSION per impostare la versione su 5 o versione successiva. Le versioni precedenti alla versione 5 non supportano l'eliminazione di colonna zero.

 

È possibile recuperare e modificare le proprietà di una colonna esistente usando i messaggi LVM_GETCOLUMN e LVM_SETCOLUMN. Per recuperare o modificare la larghezza di una colonna, usare i messaggi LVM_GETCOLUMNWIDTH e LVM_SETCOLUMNWIDTH.

A meno che non venga specificato lo stile della finestra LVS_NOCOLUMNHEADER, le intestazioni di colonna vengono visualizzate nella modalità report. L'utente può fare clic su un'intestazione di colonna, causando l'invio di un codice di notifica LVN_COLUMNCLICK alla finestra padre. In genere, la finestra padre ordina il controllo elenco in base alla colonna specificata quando si verifica il clic. L'utente può anche trascinare le guide di colonna tra le intestazioni per ridimensionare le colonne.

I controlli visualizzazione elenco possono visualizzare immagini accanto ai titoli delle colonne. Per implementare questa funzionalità, specificare il valore LVCF_IMAGE e assegnare l'indice dell'immagine al membro iImage nella struttura LVCOLUMN.

I controlli visualizzazione elenco possono impostare l'ordine di visualizzazione delle colonne. Per implementare questa funzionalità, specificare il valore LVCF_ORDER e assegnare l'ordine di colonna al membro iOrder nella strutturaLVCOLUMN. L'ordine delle colonne è in base zero ed è in ordine da sinistra a destra. Ad esempio, zero indica la colonna più a sinistra.

List-View posizione di scorrimento

A meno che non sia specificato lo stile della finestra LVS_NOSCROLL, un controllo visualizzazione elenco può essere scorribile per mostrare più elementi rispetto a quelli che possono entrare nell'area client del controllo. È possibile recuperare la posizione di scorrimento e le informazioni correlate di un controllo visualizzazione elenco, scorrere un controllo visualizzazione elenco in base a una quantità specificata o scorrere un controllo visualizzazione elenco in modo che sia visibile una voce di elenco specificata.

Nella visualizzazione icona o nella visualizzazione icona piccola la posizione di scorrimento corrente è definita dall'origine della visualizzazione . L'origine della visualizzazione è il set di coordinate, rispetto all'area visibile del controllo visualizzazione elenco, che corrispondono alle coordinate di visualizzazione (0, 0). Per recuperare l'origine della visualizzazione corrente, usare il messaggio LVM_GETORIGIN. Questo messaggio deve essere usato solo nella visualizzazione a icona o piccola icona; produrrà un errore nella visualizzazione a elenco o a report.

Nella visualizzazione elenco o report la posizione di scorrimento corrente viene definita dall'indice superiore . L'indice superiore è l'indice del primo elemento visibile nel controllo visualizzazione elenco. Per recuperare l'indice superiore corrente, usare il messaggio LVM_GETTOPINDEX. Questo messaggio restituisce un risultato valido solo in visualizzazione elenco o report; restituisce zero nella visualizzazione icona o icona piccola.

È possibile utilizzare il messaggio di LVM_GETVIEWRECT per recuperare il rettangolo di delimitazione di tutti gli elementi in un controllo elenco visualizzato, relativo all'area visibile del controllo.

Il messaggio LVM_GETCOUNTPERPAGE restituisce il numero di elementi che rientrano in una pagina del controllo visualizzazione elenco. Questo messaggio restituisce un risultato valido solo nelle visualizzazioni elenco e report; nelle visualizzazioni icona e icona piccola restituisce il numero totale di elementi.

Per scorrere un controllo visualizzazione elenco in base a una quantità specifica, utilizzare il messaggio LVM_SCROLL. Usando il messaggio LVM_ENSUREVISIBLE, è possibile scorrere il controllo visualizzazione elenco, se necessario, per assicurarsi che un elemento specificato sia visibile.

modifica delle etichette List-View

Un controllo visualizzazione elenco con lo stile della finestra LVS_EDITLABELS consente a un utente di editare le etichette degli elementi direttamente. L'utente inizia a modificare facendo clic sull'etichetta di un elemento che è attualmente selezionato. In alternativa, un'applicazione può iniziare a modificare automaticamente usando il messaggio LVM_EDITLABEL. Il controllo di visualizzazione elenco notifica la finestra madre quando inizia la modifica e quando viene annullata o completata. Al termine della modifica, la finestra padre è responsabile dell'aggiornamento dell'etichetta dell'elemento, se appropriato.

All'inizio della modifica delle etichette, viene creato, posizionato e inizializzato un controllo di modifica . Prima che venga visualizzato, il controllo "visualizzazione elenco" invia alla finestra madre un codice di notifica LVN_BEGINLABELEDIT. Se è necessario modificare il processo di modifica delle etichette, è possibile implementare un gestore per questa notifica.

Un uso per un gestore di notifica LVN_BEGINLABELEDIT consiste nel controllare le etichette che l'utente può modificare. Per impedire la modifica delle etichette, restituire un valore diverso da zero. Per personalizzare la modifica delle etichette, chiedere al gestore di notifica di recuperare un handle per il controllo di modifica inviando un messaggio LVM_GETEDITCONTROL al controllo visualizzazione elenco. Dopo aver ottenuto tale handle, è possibile personalizzare il controllo di modifica inviando i normali messaggi di EM_XXX. Ad esempio, per limitare la quantità di testo che un utente può immettere, inviare il controllo di modifica un messaggio di EM_LIMITTEXT. È possibile modificare il testo predefinito del controllo di modifica con SetWindowText. È anche possibile sottoclassare il controllo di modifica per intercettare ed eliminare caratteri non validi.

Quando viene annullata o completata la modifica delle etichette, un controllo di visualizzazione elenco invia alla finestra principale un codice di notifica LVN_ENDLABELEDIT. Il parametro lParam è l'indirizzo di una struttura diNMLVDISPINFO. L'elemento membro di questa struttura è una struttura LVITEM il cui membro iItem identifica l'elemento. Se la modifica viene annullata, il membro pszText della struttura LVITEM è NULL ; in caso contrario, pszText è l'indirizzo del testo modificato. La finestra padre è responsabile dell'aggiornamento dell'etichetta dell'elemento qualora si desideri mantenere quella nuova.

colori List-View

Un'applicazione può recuperare e impostare tre colori per un controllo della visualizzazione elenco.

Colore Messaggi usati per recuperare e impostare i colori
Colore del testo LVM_GETTEXTCOLOR, LVM_SETTEXTCOLOR
Colore di sfondo del testo LVM_GETTEXTBKCOLOR, LVM_SETTEXTBKCOLOR
Colore di sfondo della finestra LVM_GETBKCOLOR, LVM_SETBKCOLOR

 

Per personalizzare in modo più significativo l'aspetto di un controllo di tipo elenco, utilizzare NM_CUSTOMDRAW (visualizzazione elenco) oppure utilizzare stili visivi (vedere Stili Visivi e Abilitazione degli Stili Visivi).

Disposizione di elementi dell'elenco per gruppo

Le funzionalità di raggruppamento del controllo visualizzazione elenco consentono di raggruppare visivamente set di elementi logicamente correlati. I gruppi possono essere creati in base a proprietà, attributi o altre caratteristiche degli elementi. Questi gruppi sono in genere separati sullo schermo da un'intestazione orizzontale che contiene il nome del gruppo. La schermata seguente mostra gli elementi raggruppati.

schermata di un controllo di visualizzazione elenco, con cani in un gruppo e gatti in un altro gruppo

Usare la strutturaLVGROUPper archiviare informazioni su un gruppo, ad esempio il testo dell'intestazione e del piè di pagina, lo stato corrente del gruppo e così via. L'API di raggruppamento include messaggi che consentono di gestire gruppi ed elementi di gruppo aggiungendo elementi a gruppi, aggiungendo gruppi a visualizzazioni, ordinando elementi di gruppo e eseguendo query sui gruppi per le dimensioni degli elementi e altre informazioni. Ad esempio, è possibile impostare e recuperare i parametri di visualizzazione per ogni gruppo usando le macro ListView_SetGroupMetrics e ListView_GetGroupMetrics.

Il raggruppamento è disponibile in tutte le visualizzazioni, ad eccezione della visualizzazione elenco. Non è disponibile nei controlli con lo stile LVS_OWNERDATA.

Per altre informazioni, vedere Using List-View Controls.

Simboli di inserimento

Le indicazioni di inserimento mostrano agli utenti dove verranno posizionati gli elementi che sono stati trascinati. I segni di inserimento vengono attualmente visualizzati quando l'utente trascina un elemento nel menu Start o nella barra di avvio veloce. Anche il cursore di inserimento funziona per gli elenchi impostati su disposizione automatica. Quando un utente trascina un elemento in un punto tra due altri elementi, il segno di inserimento mostra la nuova posizione prevista dell'elemento. La schermata seguente mostra un segno di inserimento.

uno screenshot che mostra un segno di inserimento quando si trascina un file tra due altri in un controllo elenco

Gli elementi API del contrassegno di inserimento consentono il posizionamento dei contrassegni di inserimento fornendo messaggi e flag che eseguono il rilevamento degli hit, che specificano la posizione e l'aspetto del contrassegno di inserimento per elemento e che eseguono una query per informazioni sulle dimensioni e l'aspetto correnti del contrassegno di inserimento.

Vedere anche