Informazioni sui controlli visualizzazione elenco

Vedere l'esempio di controllo Virtual listview.

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

Stili e visualizzazioni visualizzazione elenco

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 vengono descritte le viste.

Nome vista Descrizione
Visualizzazione icona Specificato dallo stile della finestra LVS_ICON o passando LV_VIEW_ICON con il messaggio LVM_edizione Standard TVIEW. 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_edizione Standard TVIEW. 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_edizione Standard TVIEW. 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.
Visualizzazione report (dettagli) Specificato dallo stile della finestra LVS_REPORT o passando LV_VIEW_DETAILS con LVM_edizione Standard TVIEW. 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 affiancata Versione 6 e successive. Specificato passando LV_VIEW_TILE con LVM_edizione Standard TVIEW. 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" tramite SetWindowTheme.

La schermata seguente mostra la visualizzazione dei dettagli.

screen shot that shows information in five columns and seven rows

La schermata seguente mostra la visualizzazione icona.

screen shot that shows only the name of each pet and an icon indicating the species

La schermata seguente mostra la visualizzazione elenco.

screen shot that shows, for each pet, a large icon next the text of the pet's name, breed, and price

La schermata seguente mostra la visualizzazione riquadro.

tile view.

È 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 Stili finestra visualizzazione elenco.

Stili di visualizzazione elenco estesi

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

Sono presenti due messaggi che impostano e recuperano informazioni sullo stile esteso, LVM_edizione Standard TEXTENDEDLISTVIEWSTYLE e LVM_GETEXTENDEDLISTVIEWSTYLE. Anziché inviare i messaggi in modo esplicito, è possibile utilizzare le macro corrispondenti seguenti: ListView_SetExtendedListViewStyle, ListView_SetExtendedListViewStyleEx e ListView_GetExtendedListViewStyle.

Stile visualizzazione elenco 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 proprietario riceve il carico di gestione dei dati dell'elemento. 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 visualizzazione elenco virtuale mantiene informazioni sugli elementi molto piccole. Fatta eccezione per la selezione dell'elemento e le informazioni sullo stato attivo, 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 hint 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 Visualizzazione elenco 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 LVS_AUTOARRANGE.

Per consentire la visualizzazione degli elementi nell'elenco, è prima necessario inviare il messaggio LVM_edizione Standard TITEMCOUNT, 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_edizione Standard TTILEINFO e 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 archiviano informazioni specifiche dell'elemento. Di conseguenza, gli unici flag di stato dell'elemento validi che è possibile applicare a un elemento sono LVIS_edizione Standard LECTED e LVIS_FOCUedizione Standard D. 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 eseguire una query sul controllo della visualizzazione elenco per queste immagini inviando un messaggio LVM_edizione Standard TCALLBACKMASK.

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.

Message 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 un callback di notifica.
LVM_DELETEITEM È supportato solo per l'integrità della selezione e non elimina effettivamente un elemento.
LVM_GETITEMSTATE Restituisce solo gli stati di stato attivo e di selezione, ovvero gli stati archiviati dal controllo visualizzazione elenco.
LVM_GETNEXTITEM Non supporta i criteri di ricerca per la visualizzazione elenco LVNI_CUT, LVNI_HIDDEN o LVNI_DROPHILITED. Sono supportati tutti gli altri criteri.
LVM_GETWORKAREAS Non è supportata.
LVM_INedizione Standard RTITEM È supportato solo per l'integrità della selezione.
LVM_edizione Standard TITEM Non è supportata. Per impostare lo stato dell'elemento, usare il messaggio ListView_SetItemState.
LVM_edizione Standard TITEMCOUNT Imposta il numero di elementi attualmente presenti nell'elenco. Se il controllo visualizzazione elenco invia una notifica che richiede dati per qualsiasi elemento fino al set massimo, il proprietario deve essere pronto a fornire tali dati. I parametri del messaggio supportano i controlli della visualizzazione elenco virtuale.
LVM_edizione Standard TITEMPOSITION Non è supportata.
LVM_edizione Standard TITEMSTATE Consente di modificare solo gli stati di selezione e stato attivo per l'elemento.
LVM_edizione Standard TITEMTEXT Non è supportata. È responsabilità dell'applicazione mantenere i testi dell'articolo.
LVM_edizione Standard TWORKAREAS Non è supportata.
LVM_SORTITEMS Non è supportata. È responsabilità dell'applicazione presentare gli elementi nell'ordine desiderato.

 

Gestione dei codici di notifica del controllo visualizzazione elenco virtuale

I controlli visualizzazione elenco con lo stile 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 mantiene da solo 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 sugli elementi richiesti 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 struttura LVFINDINFO, che è un membro della struttura NMLVFINDITEM. Il proprietario deve essere pronto a cercare un elemento che corrisponda alle informazioni fornite dal controllo visualizzazione elenco. Il proprietario restituisce l'indice dell'elemento se ha esito positivo oppure -1 se non viene trovato alcun elemento corrispondente.

 

Gestione della 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 WM_NOTIFY, con il valore lParam che funge da indirizzo di una struttura NMLVCACHEHINT.

La struttura NMLVCACHEHINT include due membri integer, 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.

Aree di lavoro visualizzazione elenco

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 posizionare un nuovo elemento all'interno di un'area di lavoro specifica, è prima necessario creare l'elemento e quindi usare il LVM_edizione Standard TITEMPOSITION o il messaggio LVM_edizione StandardTITEMPOSITION32 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.

screen shot of a list-view control with one working area in each quadrant of the client area

È 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_edizione Standard TWORKAREAS e possono essere recuperate con il messaggio di LVM_GETWORKAREAS. Entrambi questi messaggi accettano l'indirizzo di una matrice di strutture RECT come lParam e il numero di strutture RECT come wParam. I membri sinistro e superiore di queste strutture specificano le coordinate dell'angolo superiore sinistro (origine) dell'area di lavoro e i membri destro e 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 il tipo di visualizzazione viene modificato. 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 (destra a sinistra) maggiore della larghezza del client del controllo determina la visualizzazione degli elementi a tale larghezza e 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 membro sinistro o 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 visualizzazione elenco

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.
  • Elenco di immagini che contiene immagini di stato, visualizzate a sinistra dell'icona di dimensioni intere o piccole. È 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 contenere anche 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 in 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 di 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.

Elementi e elementi secondari della visualizzazione elenco

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 messaggio LVM_edizione Standard TITEMTEXT o LVM_edizione Standard TITEM. 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 elemento secondario della visualizzazione elenco. Il membro iItem è l'indice in base zero dell'elemento. Il membro iSubItem è l'indice in base uno di un elemento secondario o zero se la struttura contiene informazioni su un elemento. Membri aggiuntivi specificano il testo, l'icona, lo stato e i dati dell'elemento dell'elemento. I dati degli elementi sono un valore definito dall'applicazione associato a un elemento della visualizzazione elenco.

Per aggiungere un elemento a un controllo visualizzazione elenco, utilizzare il messaggio LVM_INedizione Standard RTITEM, specificando l'indirizzo di una struttura LVITEM. Prima di aggiungere più elementi, è possibile inviare il controllo a un messaggio LVM_edizione Standard TITEMCOUNT, 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 di 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_edizione Standard TREDRAW per abilitare e disabilitare il ridisegno.

Per modificare gli attributi di un elemento della visualizzazione elenco, utilizzare il messaggio LVM_edizione Standard TITEM, specificando l'indirizzo di una struttura LVITEM. Il membro mask di questa struttura specifica gli attributi dell'elemento da modificare. Ad esempio, per modificare solo il testo di un elemento o di un elemento secondario, usare il messaggio LVM_edizione Standard TITEMTEXT.

Per recuperare informazioni su un elemento della visualizzazione elenco, utilizzare il messaggio LVM_GETITEM, specificando l'indirizzo della struttura LVITEM da compilare. Il membro mask 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 .

Stati degli elementi della visualizzazione elenco

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 Image Lists.

Lo stato di un elemento viene specificato dal membro dello 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 LVM_edizione Standard TITEMSTATE. È possibile specificare lo stato di un elemento quando lo si crea o quando si modificano gli attributi usando il messaggio LVM_edizione Standard TITEM. Per determinare lo stato corrente di un elemento, usare il messaggio LVM_GETITEMSTATE o LVM_GETITEM.

Per impostare l'immagine di sovrimpressione di un elemento, il membro stateMask della struttura LVITEM deve includere il valore LVIS_OVERLAYMASK e il membro dello stato deve includere l'indice in base uno dell'immagine sovrapposta spostato a sinistra a 8 bit usando 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 struttura LVITEM deve includere il valore LVIS_STATEIMAGEMASK e il membro dello stato deve includere l'indice in base uno dell'immagine di stato spostato a sinistra a 12 bit usando la macro INDEXTOSTATEIMAGEMASK. L'indice può essere zero per specificare nessuna immagine di stato.

Elementi di callback e maschera di callback

Per ognuno dei relativi elementi, un controllo visualizzazione elenco archivia in genere il testo dell'etichetta, l'indice dell'elenco di immagini delle icone dell'elemento e un set 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 visualizzazione elenco è un elemento per il quale l'applicazione archivia il testo o l'indice dell'icona o entrambi. È possibile definire gli elementi di callback quando si invia il messaggio LVM_INedizione Standard RTITEM 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 di un controllo visualizzazione elenco è un set di flag di bit che specificano gli stati dell'elemento per cui l'applicazione, anziché il controllo, archivia i dati correnti. 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_edizione Standard TCALLBACKMASK 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 contenente 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_edizione Standard TDISPINFO per notificare la modifica.

Se si modificano gli attributi o i bit di stato di un elemento di callback, usare 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.

Posizione elemento visualizzazione elenco

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 nelle coordinate di visualizzazione, che sono offset delle coordinate client in base alla posizione di scorrimento.

Per recuperare e impostare la posizione di un elemento, usare i messaggi LVM_GETITEMPOSITION e LVM_edizione Standard TITEMPOSITION. LVM_GETITEMPOSITION funziona per tutte le visualizzazioni, ma LVM_edizione Standard TITEMPOSITION 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 di LVM_HITTEST .

Per recuperare il rettangolo di delimitazione per un elemento di elenco o solo per l'icona o l'etichetta, usare 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 nel membro lParam della struttura LVITEM dell'elemento quando è stato inserito 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_edizione Standard TITEM.

È 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 uno di questi stili è presente in un controllo visualizzazione elenco, un messaggio LVM_INedizione Standard RTITEM avrà esito negativo se si tenta di inserire un elemento con LPSTR_TEXTCALLBACK come membro pszText della 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 di visualizzazione elenco

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 struttura LVCOLUMN.

Per aggiungere una colonna a un controllo visualizzazione elenco, utilizzare il messaggio LVM_INedizione Standard RTCOLUMN. 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_edizione Standard TVERSION 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_edizione Standard TCOLUMN. Per recuperare o modificare la larghezza di una colonna, usare i messaggi LVM_GETCOLUMNWIDTH e LVM_edizione Standard TCOLUMNWIDTH.

A meno che non venga specificato lo stile della finestra LVS_NOCOLUMNHEADER , le intestazioni di colonna vengono visualizzate nella visualizzazione 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 visualizzazione elenco in base alla colonna specificata quando si verifica questo 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 struttura LVCOLUMN. L'ordine delle colonne è in base zero ed è in ordine da sinistra a destra. Ad esempio, zero indica la colonna più a sinistra.

Posizione di scorrimento visualizzazione elenco

A meno che non venga specificato lo stile della finestra LVS_NOSCROLL , è possibile scorrere un controllo visualizzazione elenco per visualizzare più elementi di quelli che possono essere inseriti 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 icona o icona piccola; restituisce un errore nella visualizzazione elenco o report.

Nella visualizzazione elenco o report la posizione di scorrimento corrente è 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 visualizzazione elenco, 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 etichetta visualizzazione elenco

Un controllo visualizzazione elenco con lo stile della finestra LVS_EDITLABELS consente a un utente di modificare le etichette degli elementi sul posto. L'utente inizia a modificare facendo clic sull'etichetta di un elemento con lo stato attivo. In alternativa, un'applicazione può iniziare a modificare automaticamente usando il messaggio di LVM_EDITLABEL . Il controllo visualizzazione elenco notifica alla finestra padre 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 padre 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 quali etichette l'utente può modificare. Per impedire la modifica delle etichette, restituire un valore diverso da zero. Per personalizzare la modifica delle etichette, fare in modo che il gestore di notifica recuperi 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 la modifica delle etichette viene annullata o completata, un controllo visualizzazione elenco invia alla finestra padre un codice di notifica LVN_ENDLABELEDIT . Il parametro lParam è l'indirizzo di una struttura NMLVDISPINFO. Il membro dell'elemento 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 se vuole mantenere la nuova etichetta.

Colori visualizzazione elenco

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

Colore Messaggi usati per recuperare e impostare i colori
Colore del testo LVM_GETTEXTCOLOR, LVM_edizione Standard TTEXTCOLOR
Colore di sfondo del testo LVM_GETTEXTBKCOLOR, LVM_edizione Standard TTEXTBKCOLOR
Colore di sfondo della finestra LVM_GETBKCOLOR, LVM_edizione Standard TBKCOLOR

 

Per personalizzare l'aspetto di un controllo visualizzazione elenco in modo più significativo, usare NM_CUSTOMDRAW (visualizzazione elenco) o usare gli stili di visualizzazione (vedere Stili di visualizzazione e Abilitazione degli stili di visualizzazione).

Disposizione di elementi elenco per gruppo

Le funzionalità di raggruppamento del controllo visualizzazione elenco consentono di raggruppare visivamente set di elementi correlati in modo visivo. 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.

screen shot of a list-view control, with dogs in one group and cats in another group

Usare la struttura LVGROUP per 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 Uso dei controlli visualizzazione elenco.

Segni di inserimento

I segni di inserimento mostrano agli utenti dove verranno posizionati gli elementi trascinati. I segni di inserimento vengono attualmente visualizzati quando l'utente trascina un elemento nel menu Start o nella barra di avvio veloce. Il contrassegno di inserimento funziona anche per gli elenchi impostati su range automatico. Quando un utente trascina un elemento in un punto intermedio tra due elementi, il segno di inserimento indica la nuova posizione prevista dell'elemento. La schermata seguente mostra un segno di inserimento.

screen shot that shows an insertion mark when dragging one file between two others in a list-view control

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.

Vedi anche