Tutorial 19: Tree View Control

From UIC

Tutorial 19: Tree View Control

Tutorial 19: Tree View Control
Author:	Iczelion
Email:	Translate: nOtEtA
Website:	Mirror
Date:	03/02/2009 (dd/mm/yyyy)
Level:
Language:	Italian
Comments:	Formattazione Wiki: Antelox

Introduzione

In questo tutorial, impareremo come usare un tree view control. Inoltre, impareremo anche come fare il drag and drop sotto un tree view control e come usare una lista di immagini con esso.

Tools

Esempio

Essay

Un tree view control è un genere speciale di finestra che rappresenta gli oggetti nell'ordine gerarchico. Un esempio di esso è il pannello di sinistra di Windows Explorer. Potete usare questo controllo per mostrare i rapporti fra gli oggetti. Potete creare un tree view control chiamando CreateWindowEx, passando " SysTreeView32 " come nome della classe o incorporandolo in una finestra di dialogo. Non dimenticatevi di mettere la chiamata a InitCommonControls nel vostro codice. Ci sono parecchi stili specifici per il tree view control. Questi tre sono quelli principalmente usati.

TVS_HASBUTTONS: Visualizza i tasti più (+) e meno (-) vicino alle voci principali. L'utente clicca sui tasti per espandere o sprofondare la lista di voci figlie di una voce principale. Per includere i tasti con le voci alla radice di un albero, TVS_LINESATROOT deve essere specificato.

TVS_HASLINES: Usa righe per mostrare la gerarchia delle voci.

TVS_LINESATROOT: Usa righe per collegare le voci alla radice dell'albero. Questo valore è ignorato se TVS_HASLINES non è specificato.

Il tree view control, come altri common controls, comunica con la finestra generatrice tramite messaggi. La finestra generatrice può trasmettere i vari messaggi ad esso ed il tree view control può trasmettere i messaggi " di notifica " alla relativa finestra generatrice. A questo riguardo, il tree view control non è differente da qualsiasi finestra. Quando qualcosa che lo interessa avviene, trasmette un messaggio WM_NOTIFY alla finestra generatrice accompagnato da informazioni.

WM_NOTIFY

wParam: Control ID, questo valore non è garantito che sia unico così noi non lo usiamo. Invece, usiamo hwndFrom o IDFrom membro della struttura NMHDR puntata da lParam

lParam: Puntatore alla struttura NMHDR. Alcuni comandi possono passare un puntatore a una struttura più grande ma essa deve avere una struttura NMHDR come relativo primo membro. Quindi, quando avete lParam, potete essere sicuri che punta almeno a una struttura NMHDR.

(Date uno sguardo all'API Reference per maggiori informazioni :D NdT)

Esaminiamo la struttura NMHDR.

hwndFrom è l' handle del controllo che trasmette il messaggio WM_NOTIFY.

idFrom è l'ID del controllo che trasmette questo messaggio WM_NOTIFY.

code è il messaggio attuale che il controllo desidera trasmettere alla finestra generatrice.

Le notifiche di un tree view sono quelle con TVN_ all'inizio del nome. I messaggi del tree view sono quelli con TVM_, come TVM_CREATEDRAGIMAGE. Il tree view control trasmette TVN_xxxx nel membro code di NMHDR. La finestra generatrice può trasmettere TVM_xxxx per gestirlo.

Aggiunta di voci ad un tree view control

Dopo che avete creato un tree view control, potete aggiungere delle voci ad esso. Potete fare questo inviando TVM_INSERTITEM ad esso.

TVM_INSERTITEM

wParam = 0;

lParam = puntatore a una TV_INSERTSTRUCT;

Avete bisogno di conoscere una certa terminologia a questo punto circa il rapporto fra le voci nel tree view control. Una voce può essere principale, figlia, o entrambe allo stesso tempo. Una voce principale è una voce che ha un certo numero di sottovoci connesse ad essa. Allo stesso tempo, la voce principale può essere figlia di una certa altra voce. Una voce senza un genitore è chiamata voce di radice. Ci possono essere molte voci di radice in un tree view control. Ora esamineremo la struttura TV_INSERTSTRUCT

hParent: Handle della voce principale. Se questo membro è il valore TVI_ROOT o NULL, la voce è inserita alla radice del tree-view control.

hInsertAfter: Handle della voce dopo che una nuova voce è stata inserita o uno dei seguenti valori:

• TVI_FIRST ==> Inserisce la voce all'inizio della lista.
• TVI_LAST ==> Inserisce la voce alla fine della lista.
• TVI_SORT ==> Inserisce la voce nella lista in ordine alfabetico.

Useremo soltanto TVITEM.

Questa struttura è usata per trasmettere o ricevere informazioni circa una voce del tree view, secondo i messaggi. Per esempio, con TVM_INSERTITEM, è usata per specificare gli attributi della voce da inserire nel tree view control. Con TVM_GETITEM, sarà riempita di informazioni sulla voce selezionata nel tree view.

imask è usato per specificare quale(i) membro(i) della struttura TV_ITEM è(sono) valido(i). Per esempio, se il valore di imask è TVIF_TEXT , significa che soltanto il membro pszText è valido. Potete unire insieme parecchi flags.

hItem è l' handle di una voce del tree view. Ogni voce ha una propria handle, come l' handle di una finestra. Se desiderate fare qualcosa con una voce, dovete selezionarla tramite la relativa handle.

pszText è il puntatore ad una stringa null-terminata che è l'etichetta di una voce del tree view.

cchTextMax è usato soltanto quando desiderate richiamare l'etichetta di una voce del tree view. Poichè fornirete il puntatore a un buffer in pszText, Window deve conoscere la dimensione del buffer fornito. Dovete specificare la dimensione in questo membro.

iImage ed iSelectedImage si riferiscono all'indice in una lista di immagini che contiene le immagini da mostrare quando la voce non è selezionata e quando è selezionata. Se ricordate il pannello di sinistra di Windows Explorer, le immagini delle cartelle sono specificate da questi due membri. Per inserire una voce nel tree view control, dovete riempire almeno hParent, hInsertAfter e dovreste riempire anche imask e pszText.

Aggiunta di immagini al tree view control

Se desiderate mettere un'immagine alla sinistra dell'etichetta di una voce del tree view, dovete creare una lista di immagine ed associarla al tree view control. Potete creare una lista di immagine chiamando ImageList_Create.

Questa funzione se riuscita restituisce l' handle ad una lista vuota di immagini. cx: larghezza di ogni immagine in questa lista di immagini, in pixel.

cy: altezza di ogni immagine in questa lista di immagini, in pixel. Ogni immagine in una lista di immagini deve essere uguale l'un l'altra nel formato. Se specificate una bitmap più grande, Window userà cx e cy per * tagliarla * in parecchie parti. Così dovreste preparare la vostra immagine come striscie di immagini con le dimensioni identiche.

flags: specifica i tipi di immagini in questa lista ,se sono a colori o monocromatiche e la loro intensità di colore. Consultate la vostra documentazione win32 api per più particolari.

cInitial: il numero di immagini che questa lista inizialmente conterrà. Window userà questa info per allocare la memoria per le immagini.

cGrow: la quantità di immagini che la lista può incorporare quando il sistema deve ridimensionarla per inserire nuove immagini. Questo parametro rappresenta il numero di nuove immagini che la lista ridimensionata può contenere.

Una lista di immagine non è una finestra! È soltanto un deposito di immagini ad uso di altre finestre. Dopo che una lista di immagine è stata creata, potete aggiungere le immagini ad essa chiamando ImageList_Add

Questa funzione restituisce -1 se infruttuosa.

himl: handle della lista di immagine a cui desiderate aggiungere l' immagine. È il valore restituito da una chiamata riuscita a ImageList_Create

hbmImage: handle della bitmap da aggiungere alla lista di immagini. Solitamente memorizzate la bitmap nelle risorse e la caricate con la chiamata di LoadBitmap. Si noti che non dovete specificare il numero di immagini contenute in questa bitmap perché questa informazione è determinata dai parametri cx e cy passati da ImageList_Create.

hbmMask: handle della bitmask. Se nessuna maschera è usata con la lista di immagini, questo parametro è ignorato.

Normalmente, aggiungeremo soltanto due immagini alla lista per usarle con il tree view control: una usata quando la voce del tree view non è selezionata e l'altra quando è selezionata. Quando la lista di immagini è pronta, la associate con il tree view control trasmettendo TVM_SETIMAGELIST al tree view control.

TVM_SETIMAGELIST

wParam = tipo di lista di immagini da settare. Ci sono due scelte:

• TVSIL_NORMAL Setta la lista di immagini normali, che contiene le immagini selezionata e non selezionata per una voce del tree-view.
• TVSIL_STATE Setta la lista di immagini condizionate, che contiene le immagini per le voci del tree-view che sono in una condizione prestabilita dall'utente.

lParam = handle della lista di immagini

Richiamare le informazioni circa una voce del tree view

Potete richiamare le informazioni di una voce del tree view trasmettendo il messaggio TVM_GETITEM.

TVM_GETITEM

wParam = 0

lParam = puntatore alla struttura TV_ITEM da riempire con le informazioni

Prima che trasmettiate questo messaggio, dovete riempire il membro imask con i flag(s) che specificano quale membro(i) di TV_ITEM desiderate che Window riempia. E più importante, dovete riempire hItem con l'handle della voce di cui desiderate ottenere le informazioni. E questo crea un problema: Come potete conoscere l'handle della voce di cui desiderate richiamare l'Info? Dovrete memorizzare tutte l'handle del tree view? La risposta è abbastanza semplice: non dovete. Potete trasmettere il messaggio TVM_GETNEXTITEM al tree view control per ottenere l'handle della voce del tree view che ha gli attributi che avete specificato. Per esempio, potete chiedere l'handle della prima voce figlia, della voce alla radice, della voce selezionata e così via.

TVM_GETNEXTITEM

wParam = flag

lParam = handle per una voce del tree view (necessaria soltanto per alcuni valori di flag)

Il valore in wParam è molto importante. Presento tutti i flags qui sotto:

• TVGN_CARET Ritorna la voce attualmente selezionata.

• TVGN_CHILD Ritorna la prima voce figlia della voce specificata dal parametro hItem

• TVGN_DROPHILITE Ritorna la voce che è l'obiettivo di un'operazione di drag-and-drop.

• TVGN_FIRSTVISIBLE Ritorna la prima voce visibile.

• TVGN_NEXT Ritorna la successiva voce figlia.

• TVGN_NEXTVISIBLE Ritorna la successiva voce visibile seguente a quella specificata. La voce specificata deve essere visibile. Usate il messaggio TVM_GETITEMRECT per determinare se una voce è visibile.

• TVGN_PARENT Ritorna la voce genitore della voce specificata.

• TVGN_PREVIOUS Ritorna la precedente voce figlia.

• TVGN_PREVIOUSVISIBLE Ritorna la prima voce visibile che precede quella specificata. La voce specificata deve essere visibile. Usate il messaggio TVM_GETITEMRECT per determinare se una voce è visibile.

• TVGN_ROOT Ritorna la voce radice del tree-view control.

Si può notare che, potete richiamare l'handle della voce del tree view a cui siete interessati tramite questo messaggio. SendMessage restituisce l'handle della voce del tree view se riuscita. Potete allora inserire l'handle restituita nel membro hItem di TV_ITEM da usare con il messaggio TVM_GETITEM.

Operazione di Drag and Drop nel tree view control

Questa parte è il motivo per cui ho deciso di scrivere questo tutorial. Quando ho provato a seguire l'esempio del riferimento delle api win32 ( win32.hlp di InPrise), sono stato molto frustrato perché le informazioni vitali sono difettose. Dalle prove e dagli errori, infine ho capito come effettuare il drag & drop in un tree view control e non auguro a nessuno di percorrere la stessa strada che ho fatto io. Sotto è implementato in punti il drag & drop in un tree view control.

1) Quando l'utente prova a trascinare una voce, il tree view control trasmette la notifica TVN_BEGINDRAG alla finestra generatrice. Potete usare questa occasione per creare un'immagine per il drag che è l'immagine che sarà usata per rappresentare la voce mentre è trascinata. Potete trasmettere TVM_CREATEDRAGIMAGE al tree view control per dirgli di creare un'immagine di drag per l'immagine che attualmente è usata dalla voce che sarà trascinata. Il tree view control creerà una lista di immagini con solo un' immagine per il drag e restituirà l'handle della lista di immagini a voi.

2) Dopo che l'immagine di drag è stata creata, specificate l' hotspot dell'immagine di drag chiamando ImageList_BeginDrag.

himlTrack è l'handle della lista di immagini che contiene l'immagine di drag.

iTrack è l'indice nella lista di immagine che specifica l'immagine di drag

dxHotspot specifica la distanza relativa dell' hotspot nel piano orizzontale dell'immagine di drag che sarà usata al posto del cursore del mouse, in modo da specificare quale parte dell'immagine è l' hotspot.

dyHotspot specifica la distanza relativa dell' hotspot nel piano verticale. Normalmente, iTrack deve essere 0 se specificate al tree view control di creare l'immagine di drag per voi e dxHotspot , dyHotspot possono essere 0 se desiderate che l'angolo superiore di sinistra dell'immagine di drag sia l'hotspot.

3) Quando l'immagine di drag è pronta per essere visualizzata, chiamiamo 'ImageList_DragEnter per visualizzare l'immagine di drag nella finestra.

hwndLock è l'handle della finestra che possiede l'immagine di drag. L'immagine di drag non potrà spostarsi nelle parti esterne alla finestra.

x e y sono x-e y-coordinate del posto in cui l'immagine di drag dovrebbe inizialmente essere visualizzata. Si noti che questi valori sono relativi all'angolo superiore sinistro della finestra, non alla zona del client.

4) Ora che l'immagine di drag è visualizzata nella finestra, dovrete supportare il funzionamento del drag nel tree view control. Tuttavia, c'è un piccolo problema. Dobbiamo controllare il percorso di drag con WM_MOUSEMOVE e la posizione di drop con i messaggi WM_LBUTTONUP. Tuttavia, se l'immagine di drag è sopra altre finestre figlie, la finestra generatrice non riceverà mai alcun messaggio del mouse. La soluzione è di bloccare l'input del mouse con SetCapture usando la chiamata, i messaggi del mouse saranno diretti verso la finestra specificata senza riguardo a dove il cursore del mouse si trova.

5) Tramite la ricezione di WM_MOUSEMOVE , aggiornerete il percorso di drag con la chiamata di ImageList_DragMove. Questa funzione sposta l'immagine che si sta trascinando durante l'operazione di drag-and-drop. Ancora, se volete, potete evidenziare la voce sottostante l'immagine di drag trasmettendo TVM_HITTEST per controllare se l'immagine di drag è sopra qualche voce. Se è così, potete trasmettere TVM_SELECTITEM con il flag TVGN_DROPHILITE per evidenziare la voce. Si noti che prima di inviare il messaggio TVM_SELECTITEM , dovete in primo luogo nascondere l'immagine di drag altrimenti la vostra immagine di drag lascerà delle tracce indesiderate. Potete nascondere l'immagine di drag chiamando ImageList_DragShowNolock e, dopo che l'operazione di evidenziamento è finita, chiamerete ImageList_DragShowNolock ancora per mostrare l'immagine di drag.

6) Quando l'utente libera il tasto di sinistra del mouse, dovete fare parecchie cose. Se avete evidenziato una voce, dovete rilasciarla trasmettendo TVM_SELECTITEM con ancora il flag TVGN_DROPHILITE, ma questo volta, lParam DEVE essere zero. Se non rilasciate la voce, otterrete un effetto indesiderato: quando selezionerete una certa altra voce, quella voce sarà racchiusa in un rettangolo ma sarà ancora evidenziata l'ultima voce selezionata. Successivamente, dovete chiamare ImageList_DragLeave seguito da ImageList_EndDrag. Dovete liberare il mouse chiamando ReleaseCapture. Se avete creato una lista di immagini, dovete distruggerla chiamando ImageList_Destroy. Dopo questo, potete procedere con cosa il vostro programma desiderate che faccia quando l'operazione di drag & drop è completata.

Analisi

Nella risposta a WM_CREATE , create il tree view control

Notare gli stili. TVS_xxxx sono gli stili di specifica del tree view.

Successivamente, create una lista vuota di immagini che accetterà immagini nel formato 16x16 pixel, colore a 16 bit ed inizialmente, conterrà 2 immagini ma potrà essere espansa a 10 se sarà necessario. Quindi caricate la bitmap dalle risorse e aggiungetela alla lista di immagini appena creata. Dopo questo , cancellate l'handle della bitmap poiché non sarà più usata. Quando la lista di immagini è pronta, associatela con il tree view control trasmettendo TVM_SETIMAGELIST al controllo.

Inserite le voci nel tree view control, cominciando dalla voce alla radice. Poiché sarà la voce alla radice, il membro hParent è NULL e hInsertAfter è TVI_ROOT. Il membro imask specifica che i membri pszText, iImage e iSelectedImage della struttura TV_ITEM sono validi. Riempite questi tre membri di valori adatti. pszText contiene l'etichetta della voce alla radice, iImage è l'indice dell'immagine nella lista di immagini che sarà visualizzata alla sinistra della voce non selezionata, ed iSelectedImage è l'indice dell'immagine nella lista di immagini che sarà visualizzata quando la voce sarà selezionata. Quando tutti i membri sono riempiti, trasmettete il messaggio TVM_INSERTITEM al tree view control per aggiungere la voce alla radice.

Dopo che la voce alla radice è stata aggiunta, potete attaccare le voci figlie, ad essa. hParent ora è riempito con l'handle della voce del genitore. Ed useremo le stesse immagini nella lista di immagini in modo da non cambiare i membri iSelectedImage e iImage.

Ora quando l'utente prova a trascinare una voce, il tree view control trasmette il messaggio WM_NOTIFY con TVN_BEGINDRAG come codice. lParam è il puntatore ad una struttura NM_TREEVIEW che contiene parecchie informazioni di cui abbiamo bisogno. Mettete il relativo valore in edi ed usate edi come puntatore alla struttura NM_TREEVIEW. assume edi:ptr NM_TREEVIEW è un modo di dire a MASM di trattare edi come puntatore alla struttura NM_TREEVIEW. Quindi crate un'immagine di drag trasmettendo TVM_CREATEDRAGIMAGE al tree view control. Esso restituisce l'handle alla lista di immagini recentemente creata con l'immagine di drag all'interno. Chiamate ImageList_BeginDrag per regolare l'hotspot nell'immagine di drag. Quindi azionate l'operazione di drag chiamando ImageList_DragEnter. Questa funzione visualizza l'immagine di drag alla posizione specificata nella finestra specificata. Usiamo la struttura ptDrag che è un membro della struttura NM_TREEVIEW come il punto in cui l'immagine di drag dovrebbe essere inizialmente mostrata. Dopo ciò, bloccate l'input del mouse e regolate i flags per indicare che inizia la modalità di drag.

Ora ci concentreremo su WM_MOUSEMOVE. Quando l'utente trascina l'immagine di drag avanti, la nostra finestra generatrice riceve i messaggi WM_MOUSEMOVE. In risposta a questi messaggi, aggiornate la posizione dell'immagine di drag con ImageList_DragMove. Dopo ciò, controllate se l'immagine di drag è sopra una certa voce. Fate questo trasmettendo il messaggio TVM_HITTEST al tree view control con un punto da controllare. Se l'immagine di drag è sopra una certa voce, evidenziate quella voce trasmettendo il messaggio TVM_SELECTITEM con il flag TVGN_DROPHILITE al tree view control. Durante l'operazione di evidenziamento, nascondete l'immagine di drag in modo che non lasci delle macchie sgradevoli sul tree view control.

Quando l'utente libera il tasto di sinistra del mouse, l'operazione di drag è alla fine. Lasciate la modalità di drag chiamando ImageList_DragLeave, seguita da ImageList_EndDrag e da ImageList_Destroy. Ricreate le voci del tree view in modo corretto, controllate anche l'ultima voce evidenziata e la selezionate. Dovete poi deselezionarla altrimenti le altre voci non verranno evidenziate quando selezionate. Ed infine, liberate il bloccaggio del mouse.

Disclaimer