Informazioni sui controlli visualizzazione albero

Un controllo visualizzazione albero è una finestra che visualizza un elenco gerarchico di elementi, ad esempio le intestazioni di un documento, le voci di un indice o i file e le directory in un disco. Ogni elemento è costituito da un'etichetta e da un'immagine bitmap facoltativa e a ogni elemento può essere associato un elenco di elementi secondari. Facendo clic su un elemento, l'utente può espandere o comprimere l'elenco associato di elementi secondari.

La figura seguente mostra un semplice controllo visualizzazione albero con un nodo radice, un nodo espanso e un nodo compresso. Il controllo usa una bitmap per l'elemento selezionato e un'altra bitmap per altri elementi.

Dopo aver creato un controllo visualizzazione albero, aggiungere, rimuovere, disporre o modificare gli elementi inviando messaggi al controllo. Ogni messaggio include una o più macro corrispondenti che è possibile usare invece di inviare il messaggio in modo esplicito.

In questa sezione vengono illustrati gli argomenti seguenti.

• Stili visualizzazione albero
• Elementi padre e figlio
• Etichette degli elementi
• Modifica delle etichette della visualizzazione ad albero
• Posizione elemento visualizzazione albero
• Panoramica degli stati degli elementi della visualizzazione ad albero
• Selezione dell'elemento
• Informazioni sull'elemento
• Elenchi di immagini della visualizzazione ad albero
• Operazioni di trascinamento della selezione
• Messaggi di notifica del controllo visualizzazione albero
• Elaborazione dei messaggi di controllo visualizzazione albero predefinita
• Argomenti correlati

Stili visualizzazione albero

Gli stili di visualizzazione ad albero regolano gli aspetti dell'aspetto di un controllo visualizzazione albero. Gli stili iniziali vengono impostati quando si crea il controllo visualizzazione albero. È possibile recuperare e modificare gli stili dopo aver creato il controllo visualizzazione albero usando le funzioni GetWindowLong e SetWindowLong.

Lo stile TVS_HASLINES migliora la rappresentazione grafica della gerarchia di un controllo visualizzazione albero disegnando linee che collegano gli elementi figlio al relativo elemento padre, come illustrato nella figura seguente.

Da solo, questo stile non disegna linee nella radice della gerarchia. A tale scopo, è necessario combinare gli stili TVS_HASLINES e TVS_LINESATROOT. Il risultato è illustrato nella figura seguente.

L'utente può espandere o comprimere l'elenco di elementi figlio di un elemento padre facendo doppio clic sull'elemento padre. Un controllo visualizzazione albero con lo stile TVS_HASBUTTONS aggiunge un pulsante a sinistra di ogni elemento padre. L'utente può fare clic sul pulsante una volta anziché fare doppio clic sull'elemento padre per espandere o comprimere l'elemento figlio. TVS_HASBUTTONS non aggiunge pulsanti agli elementi nella radice della gerarchia. A tale scopo, è necessario combinare TVS_HASLINES, TVS_LINESATROOT e TVS_HASBUTTONS. Questa combinazione di stili è illustrata nella figura seguente.

Lo stile TVS_CHECKBOXES crea caselle di controllo accanto a ogni elemento. Se si desidera utilizzare lo stile della casella di controllo, è necessario impostare lo stile di TVS_CHECKBOXES (con SetWindowLong) dopo aver creato il controllo visualizzazione albero e prima di popolare l'albero. In caso contrario, le caselle di controllo potrebbero essere deselezionate, a seconda dei problemi di intervallo. La figura seguente mostra lo stile della casella di controllo.

Lo stile TVS_FULLROWedizione Standard LECT fa sì che l'evidenziazione della selezione si estenda sulla larghezza intera del controllo, non solo sull'elemento stesso. La figura seguente mostra questo stile.

Lo stile TVS_EDITLABELS consente all'utente di modificare le etichette degli elementi della visualizzazione ad albero. Per altre informazioni sulla modifica delle etichette, vedere Modifica delle etichette della visualizzazione ad albero.

Per altre informazioni su questi e altri stili, vedere Stili finestra controllo visualizzazione albero.

Elementi padre e figlio

A qualsiasi elemento di un controllo visualizzazione albero può essere associato un elenco di elementi secondari, denominati elementi figlio. Un elemento con uno o più elementi figlio viene chiamato elemento padre. Un elemento figlio viene visualizzato sotto il relativo elemento padre ed è rientrato per indicare che è subordinato all'elemento padre. Un elemento che non ha un elemento padre viene visualizzato all'inizio della gerarchia e viene chiamato elemento radice.

Per aggiungere un elemento a un controllo visualizzazione albero, inviare il messaggio TVM_INedizione Standard RTITEM al controllo . Il messaggio restituisce un handle al tipo HTR edizione Enterprise ITEM, che identifica in modo univoco l'elemento. Quando si aggiunge un elemento, è necessario specificare l'handle per l'elemento padre del nuovo elemento. Se si specifica NULL o il valore TVI_ROOT anziché un handle di elemento padre nella struttura TVIN edizione Standard RTSTRUCT, l'elemento viene aggiunto come elemento radice.

In qualsiasi momento, lo stato dell'elenco di elementi figlio di un elemento padre può essere espanso o compresso. Quando lo stato viene espanso, gli elementi figlio vengono visualizzati sotto l'elemento padre. Quando viene compresso, gli elementi figlio non vengono visualizzati. L'elenco passa automaticamente tra gli stati espansi e compressi quando l'utente fa doppio clic sull'elemento padre o, se l'elemento padre ha lo stile TVS_HASBUTTONS , quando l'utente fa clic sul pulsante associato all'elemento padre. Un'applicazione può espandere o comprimere gli elementi figlio usando il messaggio TVM_EXPAND.

Un controllo visualizzazione albero invia alla finestra padre un messaggio di notifica TVN_ITEMEXPANDING quando l'elenco di elementi figlio di un elemento padre sta per essere espanso o compresso. La notifica offre a un'applicazione la possibilità di impedire la modifica o di impostare gli attributi dell'elemento padre che dipendono dallo stato dell'elenco di elementi figlio. Dopo aver modificato lo stato dell'elenco, il controllo visualizzazione albero invia alla finestra padre un messaggio di notifica TVN_ITEMEXPANDED .

Quando un elenco di elementi figlio viene espanso, viene rientrato rispetto all'elemento padre. È possibile impostare la quantità di rientro usando il messaggio TVM_edizione Standard TINDENT o recuperare l'importo corrente utilizzando il messaggio TVM_GETINDENT.

Un controllo visualizzazione albero usa la memoria allocata dall'heap del processo che crea il controllo visualizzazione albero. Il numero massimo di elementi in una visualizzazione albero si basa sulla quantità di memoria disponibile nell'heap.

Etichette degli elementi

In genere si specifica il testo dell'etichetta di un elemento quando si aggiunge l'elemento al controllo visualizzazione albero. Il messaggio TVM_INedizione Standard RTITEM include una struttura TVITEM che definisce le proprietà dell'elemento, inclusa una stringa contenente il testo dell'etichetta.

Un controllo visualizzazione albero alloca memoria per l'archiviazione di ogni elemento; il testo delle etichette degli elementi occupa una parte significativa di questa memoria. Se l'applicazione mantiene una copia delle stringhe nel controllo visualizzazione albero, è possibile ridurre i requisiti di memoria del controllo specificando il valore LPSTR_TEXTCALLBACK nel membro pszText di TVITEM anziché passare stringhe effettive alla visualizzazione albero. L'utilizzo di LPSTR_TEXTCALLBACK fa sì che il controllo visualizzazione albero recuperi il testo dell'etichetta di un elemento dalla finestra padre ogni volta che l'elemento deve essere ridisegnato. Per recuperare il testo, il controllo visualizzazione albero invia un messaggio di notifica TVN_GETDISPINFO , che include l'indirizzo di una struttura NMTVDISPINFO . La finestra padre deve riempire i membri appropriati della struttura inclusa.

Modifica delle etichette della visualizzazione ad albero

L'utente può modificare direttamente le etichette degli elementi in un controllo visualizzazione albero con lo stile TVS_EDITLABELS. L'utente inizia a modificare facendo clic sull'etichetta dell'elemento con lo stato attivo. Un'applicazione inizia a modificare usando il messaggio di TVM_EDITLABEL . Il controllo visualizzazione albero notifica alla finestra padre all'inizio della modifica e quando viene annullato o completato. Al termine della modifica, la finestra padre è responsabile dell'aggiornamento dell'etichetta dell'elemento, se appropriato.

All'inizio della modifica delle etichette, un controllo visualizzazione albero invia alla finestra padre un messaggio di notifica TVN_BEGINLABELEDIT. Elaborando questa notifica, un'applicazione può consentire la modifica di alcune etichette e impedire la modifica di altre. La restituzione di zero consente la modifica e la restituzione di un valore diverso da zero ne impedisce la restituzione.

Quando la modifica delle etichette viene annullata o completata, un controllo visualizzazione albero invia alla finestra padre un messaggio di notifica TVN_ENDLABELEDIT . Il parametro lParam è l'indirizzo di una struttura NMTVDISPINFO. Il parametro item è una struttura TVITEM che identifica l'elemento e include il testo modificato. La finestra padre è responsabile dell'aggiornamento dell'etichetta dell'elemento se vuole mantenere la nuova etichetta. Il membro pszText di TVITEM è zero se la modifica viene annullata.

Durante la modifica delle etichette, in genere in risposta al messaggio di notifica TVN_BEGINLABELEDIT , è possibile recuperare l'handle al controllo di modifica usato per la modifica delle etichette usando il messaggio di TVM_GETEDITCONTROL . È possibile inviare il controllo di modifica a un messaggio EM_edizione Standard TLIMITTEXT per limitare la quantità di testo che un utente può immettere o sottoclassare il controllo di modifica per intercettare ed eliminare caratteri non validi. Si noti, tuttavia, che il controllo di modifica viene visualizzato solo dopo l'invio di TVN_BEGINLABELEDIT.

Posizione elemento visualizzazione albero

La posizione iniziale di un elemento viene impostata quando l'elemento viene aggiunto al controllo visualizzazione albero utilizzando il messaggio TVM_INedizione Standard RTITEM. Il messaggio include una struttura TVIN edizione Standard RTSTRUCT che specifica l'handle per l'elemento padre e l'handle per l'elemento dopo il quale deve essere inserito il nuovo elemento. Il secondo handle deve identificare un elemento figlio dell'elemento padre specificato o uno di questi valori: TVI_FIRST, TVI_LAST o TVI_SORT.

Quando si specifica TVI_FIRST o TVI_LAST, il controllo visualizzazione albero posiziona il nuovo elemento all'inizio o alla fine dell'elenco di elementi figlio dell'elemento padre specificato. Quando si specifica TVI_SORT, il controllo visualizzazione albero inserisce il nuovo elemento nell'elenco di elementi figlio in ordine alfabetico in base al testo delle etichette degli elementi.

È possibile inserire l'elenco di elementi figlio di un elemento padre in ordine alfabetico usando il messaggio TVM_SORTCHILDREN. Il messaggio include un parametro che specifica se anche tutti i livelli di elementi figlio decrescente dall'elemento padre specificato vengono ordinati in ordine alfabetico.

Il messaggio TVM_SORTCHILDRENCB consente di ordinare gli elementi figlio in base ai criteri definiti dall'utente. Quando si usa questo messaggio, si specifica una funzione di callback definita dall'applicazione che il controllo visualizzazione albero può chiamare ogni volta che è necessario stabilire l'ordine relativo di due elementi figlio. La funzione di callback riceve due valori definiti dall'applicazione a 32 bit per gli elementi confrontati e un terzo valore a 32 bit specificato durante l'invio di TVM_SORTCHILDRENCB.

Panoramica degli stati degli elementi della visualizzazione ad albero

Ogni elemento in un controllo visualizzazione albero ha uno stato corrente. Le informazioni sullo stato per ogni elemento includono un set di flag di bit, nonché indici di elenco di immagini che indicano l'immagine dello stato dell'elemento e l'immagine di sovrapposizione. I flag di bit indicano se l'elemento è selezionato, disabilitato, espanso e così via. Nella maggior parte dei casi, un controllo visualizzazione albero imposta automaticamente lo stato di un elemento in modo da riflettere le azioni dell'utente, ad esempio la selezione di un elemento. Tuttavia, è anche possibile impostare lo stato di un elemento usando il messaggio TVM_edizione Standard TITEM ed è possibile recuperare lo stato corrente di un elemento usando il messaggio TVM_GETITEM. Per un elenco completo degli stati degli elementi, vedere Tree-View Control Item States.For a complete list of item states, see Tree-View Control Item States.

Lo stato corrente di un elemento viene specificato dal membro dello stato della struttura TVITEM. Un controllo visualizzazione albero potrebbe modificare lo stato di un elemento in modo da riflettere un'azione dell'utente, ad esempio la selezione dell'elemento o l'impostazione dello stato attivo sull'elemento. Inoltre, un'applicazione può modificare lo stato di un elemento per disabilitare o nascondere l'elemento o per specificare un'immagine sovrapposta o un'immagine di stato.

Quando specifichi o modifichi lo stato di un elemento, il membro della maschera di stato di TVITEM specifica i bit di stato da impostare e il membro dello stato contiene i nuovi valori per tali bit.

Per impostare l'immagine di sovrapposizione di un elemento, la maschera di stato deve includere il valore TVIS_OVERLAYMASK e lo stato deve includere l'indice in base uno dell'immagine sovrapposta spostata a sinistra a 8 bit usando la macro INDEXTOOVERLAYMASK. L'indice può essere zero per specificare nessuna immagine di sovrapposizione.

Accanto all'icona di un elemento viene visualizzata un'immagine di stato per indicare uno stato definito dall'applicazione. Le immagini di stato sono contenute in un elenco di immagini di stato specificato inviando un messaggio TVM_edizione Standard TIMAGELIST. Per impostare l'immagine dello stato di un elemento, includere il valore TVIS_STATEIMAGEMASK nel membro maschera di stato della struttura TVITEM. I bit da 12 a 15 del membro dello stato della struttura specificano l'indice nell'elenco di immagini di stato dell'immagine da disegnare.

Per impostare l'indice dell'immagine di stato, usare INDEXTOSTATEIMAGEMASK. Questa macro accetta un indice e imposta i bit da 12 a 15 in modo appropriato. Per indicare che l'elemento non ha un'immagine di stato, impostare l'indice su zero. Questa convenzione indica che l'immagine zero nell'elenco di immagini di stato non può essere usata come immagine di stato. Per isolare i bit da 12 a 15 del membro dello stato, usare la maschera TVIS_STATEIMAGEMASK. Per altre informazioni sulle immagini sovrapposte e sullo stato, vedere Elenchi di immagini di visualizzazione ad albero.

Selezione dell'elemento

Un controllo visualizzazione albero notifica alla finestra padre quando la selezione passa da un elemento a un altro inviando i messaggi di notifica TVN_edizione Standard LCHANGING e TVN_edizione Standard LCHANGED. Entrambe le notifiche includono un valore che specifica se la modifica è il risultato di un clic del mouse o di una sequenza di tasti. Le notifiche includono anche informazioni sull'elemento che sta ottenendo la selezione e sull'elemento che sta perdendo la selezione. È possibile utilizzare queste informazioni per impostare gli attributi dell'elemento che dipendono dallo stato di selezione dell'elemento. La restituzione di TRUE in risposta a TVN_edizione Standard LCHANGING impedisce la modifica della selezione e la restituzione di FAL edizione Standard consente la modifica.

Un'applicazione può modificare la selezione inviando il messaggio TVM_edizione Standard LECTITEM.

Informazioni sull'elemento

I controlli visualizzazione albero supportano diversi messaggi che recuperano informazioni sugli elementi nel controllo .

Il messaggio TVM_GETITEM può recuperare l'handle e gli attributi di un elemento. Gli attributi di un elemento includono lo stato corrente, gli indici nell'elenco di immagini del controllo delle immagini bitmap selezionate e non selezionate dell'elemento, un flag che indica se l'elemento ha elementi figlio, l'indirizzo della stringa di etichetta dell'elemento e il valore a 32 bit definito dall'elemento.

Il messaggio TVM_GETNEXTITEM recupera l'elemento della visualizzazione albero che porta la relazione specificata con l'elemento corrente. Il messaggio può recuperare l'elemento padre di un elemento, l'elemento visibile successivo o precedente, il primo elemento figlio e così via.

Il messaggio TVM_GETITEMRECT recupera il rettangolo di delimitazione per un elemento di visualizzazione albero. I messaggi TVM_GETCOUNT e TVM_GETVISIBLECOUNT recuperano rispettivamente un conteggio degli elementi in un controllo visualizzazione albero e un conteggio degli elementi che possono essere completamente visibili nella finestra del controllo visualizzazione albero. È possibile assicurarsi che un particolare elemento sia visibile usando il messaggio di TVM_ENSUREVISIBLE .

Elenchi di immagini della visualizzazione ad albero

A ogni elemento di un controllo di visualizzazione albero possono essere associate quattro immagini bitmap.

• Immagine, ad esempio una cartella aperta, visualizzata quando l'elemento è selezionato.
• Immagine, ad esempio una cartella chiusa, visualizzata quando l'elemento non è selezionato.
• Immagine di sovrimpressione disegnata in modo trasparente sull'immagine selezionata o non selezionata.
• Immagine di stato, che è un'immagine aggiuntiva visualizzata a sinistra dell'immagine selezionata o non selezionata. È possibile usare immagini di stato, ad esempio caselle di controllo selezionate e deselezionate, per indicare gli stati degli elementi definiti dall'applicazione.

Per impostazione predefinita, un controllo visualizzazione albero non visualizza immagini di elementi. Per visualizzare le immagini degli elementi, è necessario creare elenchi di immagini e associarli al controllo . Per altre informazioni sugli elenchi di immagini, vedere Elenchi di immagini.

Un controllo visualizzazione albero può avere due elenchi di immagini: un elenco di immagini normale e un elenco di immagini di stato. Un elenco di immagini normale archivia le immagini selezionate, non selezionate e sovrapposte. Un elenco di immagini di stato archivia le immagini di stato. Usare la funzione ImageList_Create per creare un elenco di immagini e usare altre funzioni dell'elenco di immagini per aggiungere bitmap all'elenco di immagini. Quindi, per associare l'elenco di immagini al controllo visualizzazione albero, usare il messaggio TVM_edizione Standard TIMAGELIST. Il messaggio TVM_GETIMAGELIST recupera un handle in uno degli elenchi di immagini di un controllo visualizzazione albero. Questo messaggio è utile se è necessario aggiungere altre immagini all'elenco.

Oltre alle immagini selezionate e non selezionate, l'elenco di immagini normali di un controllo visualizzazione albero può contenere fino a quattro immagini sovrapposte. Le immagini sovrapposte sono identificate da un indice in base uno e sono progettate per essere disegnate in modo trasparente sulle immagini selezionate e non selezionate. Per assegnare un indice di overlay mask a un'immagine nell'elenco di immagini normali, chiamare la funzione ImageList_SetOverlayImage.

Per impostazione predefinita, tutti gli elementi visualizzano la prima immagine nell'elenco delle immagini normali per gli stati selezionati e non selezionati. Inoltre, per impostazione predefinita, gli elementi non visualizzano immagini sovrapposte o immagini di stato. È possibile modificare questi comportamenti predefiniti per un elemento inviando il messaggio TVM_INedizione Standard RTITEM o TVM_edizione Standard TITEM. Questi messaggi usano la struttura TVITEM per specificare gli indici dell'elenco di immagini per un elemento.

Per specificare le immagini selezionate e non selezionate di un elemento, impostare i bit TVIF_edizione Standard LECTEDIMAGE e TVIF_IMAGE nel membro mask della struttura TVITEM e specificare gli indici dall'elenco di immagini normali del controllo nei membri iSelectImage e iImage. In alternativa, è possibile specificare il valore I_IMAGECALLBACK in iSelectImage e iImage anziché specificare gli indici. In questo modo il controllo esegue una query sulla finestra padre per un indice dell'elenco di immagini ogni volta che l'elemento sta per essere ridisegnato. Il controllo invia il messaggio di notifica TVN_GETDISPINFO per recuperare l'indice.

Per associare un'immagine di sovrimpressione a un elemento, utilizzare la macro INDEXTOOVERLAYMASK per specificare un indice della maschera di sovrapposizione nel membro dello stato della struttura TVITEM dell'elemento. È inoltre necessario impostare i bit di TVIS_OVERLAYMASK nel membro stateMask. Gli indici della maschera di sovrapposizione sono basati su uno; un indice pari a zero indica che non è stata specificata alcuna immagine di sovrimpressione.

Le immagini di stato vengono archiviate in un elenco di immagini di stato separate e identificate dal relativo indice. Per specificare l'elenco di immagini di stato, inviare un messaggio TVM_edizione Standard TIMAGELIST. A differenza del controllo visualizzazione elenco, che usa un indice basato su un solo per identificare le immagini dello stato, le immagini dello stato del controllo visualizzazione albero sono identificate da un indice in base zero. Tuttavia, un indice pari a zero indica che l'elemento non ha un'immagine di stato. Di conseguenza, l'immagine zero non può essere usata come immagine di stato. Per altre informazioni sugli stati degli elementi e sulle immagini dello stato, vedere Cenni preliminari sugli stati degli elementi di visualizzazione ad albero.

Operazioni di trascinamento della selezione

Un controllo visualizzazione albero notifica alla finestra padre quando l'utente inizia a trascinare un elemento. La finestra padre riceve un messaggio di notifica TVN_BEGINDRAG quando l'utente inizia a trascinare un elemento con il pulsante sinistro del mouse e un messaggio di notifica TVN_BEGINRDRAG quando l'utente inizia a trascinare con il pulsante destro. È possibile impedire a un controllo visualizzazione albero di inviare queste notifiche assegnando al controllo visualizzazione albero lo stile TVS_DISABLEDRAGDROP.

Si ottiene un'immagine da visualizzare durante un'operazione di trascinamento usando il messaggio TVM_CREATEDRAGIMAGE. Il controllo visualizzazione albero crea una bitmap di trascinamento in base all'etichetta dell'elemento trascinato. Il controllo visualizzazione albero crea quindi un elenco di immagini, aggiunge la bitmap e restituisce l'handle all'elenco di immagini.

È necessario specificare il codice che trascina effettivamente l'elemento. Ciò comporta in genere l'uso delle funzionalità di trascinamento delle funzioni dell'elenco di immagini e l'elaborazione dei messaggi WM_MOUedizione Standard MOVE e WM_LBUTTONUP (o WM_RBUTTONUP) inviati alla finestra padre dopo l'avvio dell'operazione di trascinamento.

Se gli elementi in un controllo visualizzazione albero devono essere le destinazioni delle operazioni di trascinamento della selezione, è necessario sapere quando il puntatore del mouse si trova su un elemento di destinazione. È possibile scoprire usando il messaggio di TVM_HITTEST . Specificare l'indirizzo di una struttura TVHITTESTINFO che contiene le coordinate correnti del puntatore del mouse. Quando la funzione SendMessage viene restituita, la struttura contiene un flag che indica la posizione del puntatore del mouse rispetto al controllo di visualizzazione albero. Se il puntatore si trova su un elemento nel controllo visualizzazione albero, la struttura contiene anche l'handle per l'elemento.

È possibile indicare che un elemento è la destinazione di un'operazione di trascinamento della selezione usando il messaggio TVM_edizione Standard TITEM per impostare lo stato sul valore di TVIS_DROPHILITED. Un elemento con questo stato viene disegnato nello stile utilizzato per indicare una destinazione di trascinamento della selezione.

Messaggi di notifica del controllo visualizzazione albero

Un controllo visualizzazione albero invia i messaggi di notifica seguenti alla relativa finestra padre sotto forma di WM_NOTIFY messaggi.

Elaborazione dei messaggi di controllo visualizzazione albero predefinita

In questa sezione viene descritta l'elaborazione dei messaggi della finestra eseguita da un controllo visualizzazione albero. I messaggi specifici dei controlli di visualizzazione albero vengono illustrati in altre sezioni di questo documento, pertanto non sono inclusi qui.

Argomenti correlati

ESEMPIO: CustDTv illustra un disegno personalizzato in un controllo TreeView (Q248496)