Programando com o TreeView

Parte 1 Editorial
Este tutorial foi desenvolvido bom base em uma tutorial em ingls e completamente readaptado para um perfeito conhecimento de uma ferramenta poderosa e pouco usada do Delphi, o TreeView, que pode facilitar o uso e estruturao dos programas de vrias formas possveis. No decorrer desse pequeno tutorial, tentei ser o mais claro possvel nas explicaes, ao mesmo tempo em que tive que me manter fiel ao contedo original. O texto possui traduo livre para facilitar o entendimento do tema abordado, no ficando restrito simplesmente ao contedo apresentado, mas buscando ir alm com exemplos prticos. Algumas partes do texto possuem indicaes (N.T.: ou nota do tradutor), que foram adicionadas por mim para complementar o contedo apresentado. Todos os exemplos dos cdigos apresentados foram comentados, buscando enriquecer o contedo e facilitar a compreenso. Os cdigo propostos possuem formatao diferenciada do restante do texto para facilitar sua identificao e entendimento. As notas de comentrio nos cdigos apresentados tambm possuem formatao diferenciada, facilitando sua identificao. Como no exemplo: {testa se o TreeView foi selecionado} if( TVEx1.Selected = nil ) then begin end; A parte 1 desse tutorial composto por quatro partes, que so a base para trabalharmos com o Treeview. Tentarei traduzir o restante do tutorial e continuar publicando nesse espao para que todos possam conhecer ou ampliar seus conhecimentos com mais essa ferramenta. Estarei aberto a crticas e sugestes e peo, desde j, para mandarem notas de apoio, complemento ou crticas para que possa aperfeioar e continuar na construo desse material. Obrigado e sucesso a todos. Contedo desse tutorial: 1. Adicionando e Removendo Ns no TreeView 2. Colocando Imagens nos Ns 1 de 17 e-mail: msarcinelli@hotmail.com cdigos comentrios

Programando com o TreeView 3. A Propriedade TreeNode.Level 4. Prevenindo a Criao de Ns Duplicados Adicionando e Removendo Ns no TreeView Este um rpido exemplo de como adicionar ou remover ns em um componente TTreeView. Crie um novo projeto no Delphi, insira um componente TreeView (N.T: paleta Win32) e dois botes (N.T: paleta Standard) em um formulrio. Siga as orientaes da tabela abaixo para a configurao dos botes e do treeview Uma sugesto pode ser vista no exemplo abaixo: Componente Caption TreeView1 Button1 Button2 Name

---------- TVEx1 Adicionar BtnAdicionar Remover BtnRemover

Adicionando um N N.T: Para entendermos o que um n, vamos fazer referncia ao Windows Explorer para mostrarmos os termos que sero usados ao longo desse tutorial: N Principal ou Root Node N filho do N Principal N filho de um outro n filho

2 de 17 e-mail: msarcinelli@hotmail.com

Programando com o TreeView Quando for adicionar um n no TreeView, voc deve saber exatamente onde fazlo. Em outras palavras voc deve saber qual n, se existir algum, ser o N Principal (N.T: N Principal aquele do qual se derivam os outros ns). Um N Principal (Root Node) no possui ns pais (esse o n principal, dele se derivaro os outros ns). Ento, sua propriedade Parent deve receber Nil (vazio) TTreeNode.Parent= nil

Os outros ns so filhos do n pai. Os ns pai podem ser um n principal ou um outro n filho. Freqentemente voc vai precisar adicionar um n filho para algum item selecionado. Porm antes de fazer isso, voc deve se certificar que existe um n selecionado. Para isso faa o seguinte teste para verificar se existe algum n no TreeView. (TreeView.Selected = nil) if( TVEx1.Selected = nil ) then begin end; No exemplo acima existem duas razes porque verificar se a propriedade Select do TreeView vazia. 1. Se a propriedade Select do TreeView vazia (TTreeView.Select = nil), indica que um n deve ser selecionado. 2. Existem ns, mas o usurio ainda no selecionou um. Aps o teste se algum n do TreeView foi selecionado, devemos testar tambm se ele est vazio, ou seja, no possui ns: if( TVEx1.Items.Count = 0 ) then begin end;

Agora que conhecemos os mtodos necessrios para determinar o estado do TreeView, vamos aprender a adicionar um N.

3 de 17 e-mail: msarcinelli@hotmail.com

Programando com o TreeView Adicionando o N Principal (Root Node)

Para adicionar um n no TreeView, voc deve usar um dos mtodos para adio de Ns. (TreeView.Items.Addxxx) Ex: TreeView.AddFirst, TreeView.AddFirstChild, TreeView.AddChild, etc. with TVEx1.Items.AddFirst( nil, 'Root' ) do begin Selected := true; end;

Se voc for adicionar um N usando o mtodo AddFirst, o n ser criado como um irmo do n passado no parmetro 1. TreeView.Items.AddFirst (parmetro1, parmetro2) No exemplo acima, como estamos criando o N Principal, no temos um n irmo, por isso informamos o parmetro 1 como vazio (nil). TVEx1.Items.AddFirst( nil, 'Principal' )

Adicionando um N Filho No exemplo, usamos o mtodo InputQuery para adicionarmos um novo n ao TreeView, passando como parmetro a varivel criada no procedimento para criao do N (N.T: Ver exemplo TreeViewEx1 em anexo). Assim o n ser adicionado como um n filho do n criado. InputQuery( 'Adicionar N', 'Insira o nome do n', sText ); Na propriedade AddChild, passamos como parmetro 1 o N selecionado (TVEx1.Select) e como parmetro 2 a varivel texto criada, que ser o nome do n. (sText) {Add the node as a child of the selected node} with TVEx1.Items.AddChild( TVEx1.Selected, sText ) do begin MakeVisible; end; Quando voc adiciona um n em um TTreeView esse n no dever ser mostrado at que esteja criado, ento o comando MakeVisible dever ser executado para mostrar o n aps ter sido criado. 4 de 17 e-mail: msarcinelli@hotmail.com

Programando com o TreeView Abaixo est listado o cdigo completo do boto Adicionar do exemplo, que dever ser colocado no evento OnClick do referido boto. procedure TFrmEx1.BtnAdicionarClick(Sender: TObject); var {Declara uma varivel string local que armazenar o nome do N criado} sText : string; InputSim: Boolean; begin {Testa se alguma coisa foi selecionada no TreeView} if( TVEx1.Selected = nil ) then begin {Testa se existe um N Principal} if( TVEx1.Items.Count = 0 ) then begin {Adiciona o N Principal se ele no existir} with TVEx1.Items.AddFirst( nil, 'Principal' ) do begin {Seleciona o N Principal criado} Selected := true; end; end else begin {Se j existir um N Principal criado, instrui o usurio a selecion-lo primeiro antes de criar um novo N} ShowMessage( 'Selecione um N' ); Exit; end; end else begin {A varivel local InputSim recebe o valor true quando o usurio clicar no boto OK, e false quando o usurio clica no boto Cancelar} InputSim := InputQuery( 'Adicionar N', 'Insira o nome do N', sText ); {Testa se a varivel InputSim possui um valor True, se possuir...} If InputSim = true then

{Testa se a varivel SText (varivel que recebe o nome do N) possui um valor, para prevenir a criao de Ns sem nome} 5 de 17 e-mail: msarcinelli@hotmail.com

Programando com o TreeView Begin If Stext = '' then Begin ShowMessage('Digite um nome para o N!'); BtnAdicionar.Click; Abort; End { ...Adiciona o N criado como um N Filho do N Selecionado } Else with TVEx1.Items.AddChildFirst( TVEx1.Selected, sText ) do begin {Torna o N visvel} MakeVisible; end; {Caso a varivel InputSim no contenha valor, a criao do N ser cancelada} Else Abort; end; end; End.// Fim do Procedimento

Removendo um N A operao de remoo de Ns bem simples. Somente devemos fazer alguns testes para verificar se algum N foi selecionado e bloquear a remoo do N Principal, que o N de onde os outros Ns se derivam. Abaixo segue o cdigo para a remoo dos Ns que dever ser colocada no procedimento OnClick do boto Remover: procedure TFrmEx1.BtnRemoverClick(Sender: TObject); begin somthing is selected, before trying to {verifica se algum n foi selecionado, retornando uma mensagem para o usurio selecionar se nenhum N for selecionado} if( TVEx1.Selected = nil ) then begin ShowMessage('Nenhum N selecionado. Seleciona um N para prosseguir!'); 6 de 17 e-mail: msarcinelli@hotmail.com

Programando com o TreeView Exit; end; {verifica se o n selecionado o N Principal, caso afirmativo, envia uma mensagem para o usurio selecionar outro N.} if( TVEx1.Selected.Level = 0 ) then begin ShowMessage('Este o N Principal e no pode ser deletado. Selecione outro N para prosseguir' ); Exit; end; { Aps feitos os testes, Deleta o n selecionado} If MessageDlg('Tem certeza que deseja excluir o N Selecionado?', MtConfirmation, [mbYes, mbNo],0 ) = mryes then TVEx1.Selected.Delete; end; End.

Aps feitos esses procedimentos, teste o seu projeto e veja que voc j tem criado uma estrutura bsica em TreeView. Agora vamos melhorar a interface do TreeView adicionando imagens nos Ns, o que dar um aspecto mais profissional ao nosso trabalho. Ento, mos obra... Colocando Imagens nos Ns As interfaces dos aplicativos que usam TreeView podem ser melhoradas usando imagens nos Ns. Esses Ns podem possuir diferentes imagens. Isto possibilitar que o usurio faa a distino entre os tipos de Ns dentro do TreeView (N.T: Qual o N Principal, o N que est sendo mostrado, etc). Podemos por exemplo atribuir uma imagem para um N que no foi clicado, uma para o N Principal e outra para o N que foi clicado. Como exemplo vamos usar 3 figuras para os Ns. Uma para o N Principal (Root Node), e as outras duas para cada um dos outros Ns Filhos, sendo que 1 figura ser para quando o N for selecionado e a outra quando no estiver. Primeiro insira um componente ImageList (N.T.: Paleta Win32) no formulrio. D um duplo clique no componente e adicione as 3 figuras (N.T.: As figuras esto na pasta do projeto que acompanha esse tutorial) Primeiro a do N Principal, depois do N quando no estiver selecionado, e finalmente a figura quando o N for clicado. 7 de 17 e-mail: msarcinelli@hotmail.com

Programando com o TreeView

Abaixo temos uma sugesto de como dever ficar o seu trabalho.

Configure a propriedade Images do TreeView com o nome do componente ImageList inserido no formulrio. Chamaremos o ImageList de ImageList1. O prximo passo ser definir constantes para representar o ndice das imagens no ImageList. Este procedimento ser muito til pois permitir alterar as imagens do ImageList sem ter que ficar alterando o cdigo do procedimento. Para adicionar as constantes no projeto, localize, na Unit do projeto, a Clusula Uses e logo abaixo declare as constantes listadas abaixo: const Img_Principal = 0; Img_Pasta_Fechada = 1; Img_Pasta_Aberta = 2; Ateno: Clique no objeto TreeView do exemplo, e altere as propriedades Images e StateImages para ImageList1, para que as imagens possam ser mostradas no TreeView na execuo do exemplo. 8 de 17 e-mail: msarcinelli@hotmail.com

Programando com o TreeView Repare que cada constante representar uma imagem que ser mostrada quando o usurio interagir com o programa. Note tambm que para cada imagem declarada tambm foi atribudo um nmero, que o ndice que essas imagens possuem dentro do ImageList, da a importncia de ordenar as figuras no ImageList. Abaixo est o cdigo para o boto Adicionar do formulrio. As partes do Cdigo que possuem um grande parntese, foram as partes atualizadas. Este procedimento dever ser inserido no evento OnClick do referido boto. procedure TFrmEx1.BtnAdicionarClick(Sender: TObject); var sText : string; InputSim : Boolean; begin {Testa se alguma coisa foi selecionada no TreeView} if( TVEx1.Selected = nil ) then begin {Testa se existe um N Principal} if( TVEx1.Items.Count = 0 ) then begin {Adiciona o N Principal se ele no existir} with TVEx1.Items.AddFirst( nil, 'Principal' ) do begin {Seleciona o N Principal criado} Selected := true; {Atravs da propriedade ImageIndex, atribui qual imagem ser mostrada no componente quando for criado. Atravs da propriedade SelectedIndex atribui qual imagem ser mostrada no componente quando ele for clicado. Repare que no caso do N Principal, para esse exemplo, usamos a mesma figura, mas nada impede que sejam usadas figuras diferentes para os projetos} ImageIndex := Img_Principal; SelectedIndex := Img_Principal; end; end else begin {Se j existir um N Principal criado, instrui o usurio a selecion-lo primeiro antes de criar um novo N} 9 de 17 e-mail: msarcinelli@hotmail.com

Programando com o TreeView ShowMessage( 'Selecione um N' ); Exit; end; end else begin {A varivel local InputSim recebe o valor true quando o usurio clicar no boto OK, e false quando o usurio clica no boto Cancelar} InputSim := InputQuery( 'Adicionar N', 'Insira o nome do N', sText ); {Testa se a varivel InputSim possui um valor True, se possuir...} If InputSim = true then {Testa se a varivel SText (varivel que recebe o nome do N) possui um valor para prevenir a criao de Ns sem nome} Begin If Stext = '' then Begin ShowMessage('Digite um nome para o N!'); BtnAdicionar.Click; Abort; End { ...Adiciona o N criado como um N Filho do N Selecionado } Else with TVEx1.Items.AddChildFirst( TVEx1.Selected, sText ) do begin {Atravs da propriedade ImageIndex, atribui qual imagem ser mostrada no componente quando for criado. Atravs da propriedade SelectedIndex atribui qual imagem ser mostrada no componente quando ele for clicado. Repare que no caso dos Ns Filhos, figuras sero diferentes, justamente para chamar ateno para o item selecionado} ImageIndex := Img_Pasta_Fechada; SelectedIndex := Img_Pasta_Aberta; {Torna o N visvel} MakeVisible; end; end {caso a varivel InputSim no contenha valor, a criao do N ser cancelada} Else 10 de 17 e-mail: msarcinelli@hotmail.com

Programando com o TreeView Abort; end; end;

Neste exemplo, vamos analisar duas propriedades mais importantes que so ImageIndex e SelectedIndex. ImageIndex SelectedIndex Indexa uma imagem, no componente ImageList, para ser mostrada quando o N no estiver selecionado. Indexa uma imagem, no componente ImageList, para ser mostrada quando o N for selecionado.

Voc tambm poder dar o mesmo valor para as propriedades ImageIndex e SelectedIndex. Isso significar que as imagens dos Ns no mudaro quando forem eles selecionados. Faa as alteraes em nosso projeto, compile, execute e vejas a diferena que as imagens proporcionam nos nosso exemplo.

Entendendo a Hierarquia de Nveis do TreeView Verificar em qual nvel um N se encontra em uma estrutura com o TreeView pode ser muito til. Obter essa informao fcil, bastando apenas verificar na propriedade Nvel do TreeView qual o ndice daquele nvel.

Como exemplo na figura acima, podemos verificar facilmente que o N Principal (Root), est no nvel 0 (N.T: O nvel 0 o Nvel Principal e no pode ser excludo). Todos os Ns que so Ns Filhos do N Principal (Root), possuem o nvel 1, nvel 2, etc. Como cada N dentro da aplicao deve representar uma nica informao, devemos evitar que existam Ns com o mesmo nome, o que causaria confuso para o usurio. Devemos ento desenvolver artifcios para evitar essa hiptese.

11 de 17 e-mail: msarcinelli@hotmail.com

Programando com o TreeView Prevenindo a Criao de Ns Duplicados

Uma coisa muito importante na hierarquia com o TreeView, que todos os Ns que pertence a um N Principal, devem ter um nico nome para identific-los, no sendo possvel a criao de Ns duplicados com o mesmo nome. Similar a restrio que possuem os arquivos, que quando criados em uma pasta devem ter um nome nico, no permitindo que sejam criados outros arquivos com esse mesmo nome. Porm, no existem propriedades especficas no TreeView para esse controle, e portanto, essas adaptaes devem ser feitas manualmente durante a criao dos cdigos. Abaixo temos uma funo exemplo para checar se o nome criado no TreeView j existe. Para implementar esse cdigo abra o projeto e localize a clusula Implementation. Logo abaixo da diretiva compiladora (N.T.:{$R *.dfm}) digite o a funo que segue: Function NomeDuplicado( Node : TTreeNode; sNewName : string; bInclusive : boolean) : boolean; var TestNode : TTreeNode; begin {comea o teste verificando se existe algum n criado} if( Node = nil ) then begin { se no existir n criado, no existem ns duplicados, ento o resultado da funo false (N.T: Essa funo realiza um teste Booleano, como resultado vamos ter como resposta true, caso existam ns com o mesmo nome, ou false, caso no existam} Result := false; Exit; end; { A varivel bInclusive retorna True se for inserido um novo N. Ser feito ento a comparao dos nomes dos Ns criados com o nome do novo N. Se na comparao existir um N com o mesmo nome do novo N criado, a funo retornar 0, atravs da Funo CompareText. Lembrando que o nome do novo N criado est na varivel sNewName no exemplo. } if( bInclusive = true ) then if( CompareText( Node.Text, sNewName ) = 0 ) then begin

12 de 17 e-mail: msarcinelli@hotmail.com

Programando com o TreeView {Se no teste de comparao dos nomes, for encontrado nome duplicado o resultado da funo recebe true, indicando que existe um N com o mesmo nome do novo N criado.} Result := true; Exit; end; {atribui varivel local criada TestNode o N que est sendo verificado, e repete o teste} TestNode := Node; Repeat {faz o teste para verificao dos nomes em todos os Ns anteriores ao N criado} TestNode := TestNode.GetPrevSibling; {se a varivel TestNode no estiver vazia} if( TestNode <> nil ) then {compara o nome do N criado com os outros Ns anteriores a este. Caso encontre algum N com o mesmo nome a funo retorna 0} if( CompareText( TestNode.Text, sNewName ) = 0 ) then begin {sendo encontrado um N com o mesmo nome do N criado, o resultado do teste verdadeiro} Result := true; Exit; end; {repete o teste at que a varivel TestNode for vazia, o que indica que j foram testados todos os Ns anteriores ao N criado} until (TestNode = nil); {continua o teste atribuindo a varivel TestNode, criada localmente na funo, o N que est sendo verificado, repetindo o teste} TestNode := Node; Repeat {comea a verificao dos Ns posteriores ao N criado}} TestNode := TestNode.GetNextSibling; {testa se a varivel TestNode diferente de vazio, o que indica que ainda existem Ns a serem testados} if( TestNode <> nil ) then 13 de 17 e-mail: msarcinelli@hotmail.com

Programando com o TreeView {faz a comparao do nome do N que est sendo testado com o nome atribudo ao novo N criado. Lembrando que este nome se encontra na varivel sNewName.} if( CompareText( TestNode.Text, sNewName ) = 0 ) then begin {encontrando nome duplicado, retorna verdadeiro para a funo} Result := true; Exit; end; {faz o teste at que a varivel TestNode esteja vazia, o que indicar que no existem mais Ns para serem testados} until (TestNode = nil); {neste caso, se no encontrar nome duplicado at o final do teste, o resultado da funo ser falso, indicando que no existem nomes duplicados nos Ns } Result := false; end;

Esta funo verifica se existem nomes duplicados executando trs passos: 1. Na incluso de um novo N, verifica se o nome atribudo ao N igual a um nome j criado) 2. Verifica o nome de todos os Ns irmos que esto antes do n criado. 3. Verifica todos os Ns Irmos que esto aps o N criado. Abaixo est uma sugesto para atualizao do boto Adicionar do exemplo O cdigo entre parnteses indica a atualizao que dever ser feita no exemplo. Este cdigo dever ser coloca no evento OnClick do referido boto. procedure TFrmEx1.BtnAdicionarClick(Sender: TObject); var sText : string; InputSim : Boolean; Begin {Testa se alguma coisa foi selecionada no TreeView} if( TVEx1.Selected = nil ) then begin {Testa se existe um N Principal} 14 de 17 e-mail: msarcinelli@hotmail.com

Programando com o TreeView if( TVEx1.Items.Count = 0 ) then Begin {Adiciona o N Principal se ele no existir} with TVEx1.Items.AddFirst( nil, 'Principal' ) do Begin {Seleciona o N Principal criado} Selected := true; {Atravs da propriedade ImageIndex, atribui qual imagem ser mostrada no componente quando for criado. Atravs da propriedade SelectedIndex atribui qual imagem ser mostrada no componente quando ele for clicado. Repare que no caso do N Principal, para esse exemplo, usamos a mesma figura, mas nada impede que sejam usadas figuras diferentes para os projetos} ImageIndex := Img_Principal; SelectedIndex := Img_Principal; end; end else begin {Se j existir um N Principal criado, instrui o usurio a selecion-lo primeiro antes de criar um novo N} ShowMessage( 'Selecione um N' ); Exit; end; end else Begin {A varivel local InputSim recebe o valor true quando o usurio clicar no boto OK, e false quando o usurio clica no boto Cancelar} InputSim := InputQuery( 'Adicionar N', 'Insira o nome do N', sText ); {Testa se a varivel InputSim possui um valor True, se possuir...} If InputSim = true then

15 de 17 e-mail: msarcinelli@hotmail.com

Programando com o TreeView

{Testa se a varivel SText (varivel que recebe o nome do N) possui um valor para prevenir a criao de Ns sem nome} Begin If Stext = '' then Begin ShowMessage('Digite um nome para o N!'); BtnAdicionar.Click; Abort; End; {Usa a funo NomeDuplicado para verificar se existe um N criado com o mesmo nome do N que ser criado} If (NomeDuplicado(TVEx1.Selected.GetFirstChild,SText,True)) then Begin ShowMessage('J existe um N criado com esse nome.' + #13 + 'Favor escolher outro nome.'); Exit; End { ...Adiciona o N criado como um N Filho do N Selecionado } Else with TVEx1.Items.AddChildFirst( TVEx1.Selected, sText ) do begin {Atravs da propriedade ImageIndex, atribui qual imagem ser mostrada no componente quando for criado. Atravs da propriedade SelectedIndex atribui qual imagem ser mostrada no componente quando ele for clicado. Repare que no caso dos Ns Filhos, figuras sero diferentes, justamente para chamar ateno para o item selecionado} ImageIndex := Img_Pasta_Fechada; SelectedIndex := Img_Pasta_Aberta; {Torna o N visvel} MakeVisible; end; end {caso a varivel InputSim no contenha valor, a criao do N ser cancelada} Else Abort; end; end;

16 de 17 e-mail: msarcinelli@hotmail.com

Programando com o TreeView

Nota Final
Aps a concluso da primeira parte desse tutorial, espero que tenham gostado e aprendido a trabalhar com o TreeView. Quando encontrei esse material na Net, logo pensei em traduzi-lo e adapt-lo para que fosse distribudo livremente, e embora tenha me custado muitas horas de dedicao a trabalho na adaptao de interminveis linhas de cdigo, sei que ser de muita valia a todos que apreciam essa poderosa ferramenta que faz parte do Delphi. Como esse tutorial distribudo livremente meu nico pagamento sero as sugestes e crticas que porventura venha a receber, e que sero de grande valia para que possa ter nimo para completar essa srie de tutoriais. Todas as pessoas que quiserem colocar essas informaes em sites particulares, esto autorizadas a faz-lo, desde que me comuniquem no endereo que consta no rodap. Obrigado a todos. Aguardem para as outras partes desse tutorial: Usando a propriedade Data do TreeView (possibilita a associao do TreeView com outros dados, como a abertura de um formulrio, por exemplo) Associando um TreeView a um ListView. Colocando uma ordem nos Ns do TreeView para facilitar a procura de dados Salvando o TreeView e os dados no disco

Obs: O projeto com todos os cdigos constantes nesse tutorial deve estar anexo a esse, para facilitar o estudo dos exemplos.

17 de 17 e-mail: msarcinelli@hotmail.com