>> Mais documentação do Visual Web Pack

Usando os componentes de lista

Conteúdo -  Criando a página -  Definindo e preservando as propriedades da caixa de listagem -  Inicializando as propriedades da caixa de listagem -  Vinculando as propriedades à caixa de listagem -  Exibindo os itens selecionados da caixa de listagem -  Adicionando e removendo os itens da caixa de listagem

Este tutorial funciona com as tecnologias e os recursos seguintes:

Componentes JavaServer Faces/ Plataforma Java EE	1.2 com Java EE 5* 1.1 com J2EE 1.4
Banco de dados Viagem	Não é necessário
Biblioteca de componentes BluePrints Ajax	Não é necessário

* Na data da publicação deste tutorial, somente o servidor de aplicativos Sun Java System oferecia suporte ao Java EE 5.

Este tutorial foi adaptado para ser usado com o Servidor de aplicativos Sun Java System PE 9.0, versão atualizada 1, e o Tomcat 5.5.17. Se você estiver usando um servidor diferente, consulte as Notas de versão e as Perguntas freqüentes para obter informações sobre problemas conhecidos e soluções sugeridas. Para obter informações detalhadas sobre os servidores suportados e a plataforma Java EE, consulte as Notas de versão.

Criando a página

1. Crie um novo projeto de aplicativo da Web visual e nomeie-o ExemploLista.

   A figura abaixo ilustra uma visualização da página que você criará nas etapas a seguir.

   Figura 1: Design da página de amostra

2. Na seção Básico da Paleta de componentes, arraste um componente Caixa de listagem e solte-o na página, em seguida, clique e arraste a margem direita do componente para torná-lo mais largo.

   A janela Esboço lista os componentes associados ao componente Caixa de listagem. O próprio componente Caixa de listagem, listbox1, controla todos os itens da lista. A caixa de listagem está associada ao listbox1DefaultOptions, um componente não visual que contém a lista de itens exibidos pela caixa de listagem e também controla os itens nela selecionados.

3. Defina a propriedade multiple do componente Caixa de listagem como True selecionando a caixa de seleção ao lado da propriedade na janela Propriedades.

   A propriedade multiple está na seção Dados da janela Propriedades. O valor True permite que o usuário selecione vários itens na caixa de listagem.
4. Arraste um componente Botão da Paleta e solte-o na página à direita da caixa de listagem. Altere o texto do botão para Enviar.

5. Arraste um componente Área de texto para a página e solte-o na caixa de listagem, em seguida, iguale a largura do componente à largura da caixa de listagem.

   A área de texto será usada para exibir os itens que serão selecionados na caixa de listagem.

Desenhando e preservando as propriedades da caixa de listagem

1. Na janela Esboço, clique com o botão direito do mouse no SessionBean1 e escolha Adicionar > Propriedade no menu pop-up.

   Observação: Se o menu Adicionar não for exibido, feche o menu pop-up e, em seguida, abra-o novamente.

   A caixa de diálogo Novo padrão de propriedade é exibida, ilustrada concluída na Figura 2. Esta caixa de diálogo é usada para criar propriedades no Bean de sessão.

   Figura 2: Caixa de diálogo Novo padrão de propriedade

2. Digite listOptions no campo Nome.

3. Digite Option[] no campo Tipo.

   Observação: A instrução importante da classe Option será adicionada na próxima seção.

4. Clique em OK para criar a propriedade.

   A raiz listOptions conterá os objetos de tipo Option. Cada objeto representa uma opção na lista. Cada opção contém um valor e um nome de exibição. O nome de exibição é sempre uma String, mas o valor pode ser qualquer tipo de objeto — que neste caso também é uma String.

5. Criar uma propriedadeSessionBean1 denominada choices de tipo String[] para manter os valores dos itens atualmente selecionados.

   1. Na janela Esboço, clique com o botão direito do mouse no SessionBean1 e escolha Adicionar > Propriedade.
   2. Na caixa de diálogo Novo padrão de propriedade, insira choices para o Nome e String[] para o Tipo, em seguida, clique em OK.

   Observação: Não será possível ver as novas propriedades abaixo do nó SessionBean1 até que a instrução importante da classe Options seja adicionada ao SessionBean1 na próxima seção.

Inicializando as propriedades da caixa de listagem

1. Na janela Esboço, clique duas vezes em SessionBean1 para abrir seu código-fonte no editor de Java.

2. No arquivo de fontes Java, clique com o botão direito do mouse e escolha Fixar importações para abrir esta caixa de diálogo.

   Esta caixa de diálogo é usada para adicionar a instrução de importação da classe Option, que representa um único item na caixa de listagem.

3. Na caixa de diálogo Fixar importações, clique na lista suspensa em Nome totalmente qualificado e escolha a classe Option correta na lista.

   • Se seu aplicativo estiver baseado no Java EE 5, selecione com.sun.webui.jsf.model.Option.
   • Se seu aplicativo estiver baseado no J2EE 1.4, selecione com.sun.rave.web.ui.model.Option.

4. Adicione as seguintes linhas de código em negrito ao construtor SessionBean1.

   Amostra de código 1: Propriedade Options do aplicativo Java EE 5

   public SessionBean1() { // Inicializar os valores da propriedade e adicionar opções // à propriedade listOptions para dar início listOptions = new Option[] { new Option("choice1", "Minha opção 1"), new Option("choice2", "Minha opção 2"), new Option("choice3", "Minha opção 3")}; choices = new String[] {}; }

   
   A terceira linha em negrito do código de amostra acima inicializa a propriedade listOptions. A três linha seguintes adicionam os itens à caixa de listagem. O primeiro parâmetro, por exemplo choice1, é o valor do item. Este valor é capturado na propriedade value do componente Caixa de listagem quando o item é selecionado. Neste caso, é usada uma String, mas você pode usar uma instância de qualquer classe Java. O segundo parâmetro, por exemplo My Choice 1, é o texto exibido na caixa de listagem. A linha final do código inicializa a propriedade choices e garante que nada seja selecionado por padrão.
5. Clique na guia Page1 para exibir esta página no Visual Designer.
6. Na janela Esboço, expanda o nó SessionBean1 e verifique se existe um nó para cada uma destas propriedades, listOptions e choices.

Vinculando as propriedades à caixa de listagem

1. Na Page1 do Visual Designer, clique com o botão direito do mouse no componente Caixa de listagem e escolha Vincular aos dados.

   A caixa de diálogo Vincular aos dados é exibida.

2. Na guia Vincular a um objeto, selecione SessionBean 1 > listOptions, como mostrado na Figura 3:

   Figura 3: Vincular a um objeto

3. Clique em OK.

   A propriedade items da caixa de listagem está agora vinculada à matriz listOptions do SessionBean1.

4. Na janela Propriedades da caixa de listagem, clique no botão de reticências (...) da propriedade selected, que está na seção Dados da janela Propriedades.

   O editor de propriedades da propriedade selected se abre com o título "listbox1 - selected".

5. Se necessário, clique na guia Vincular a um objeto, em seguida selecione choices no nó SessionBean1 e clique em OK.

   A propriedade selected da caixa de listagem está agora vinculada à matriz choices do SessionBean1.

Exibindo os itens selecionados da caixa de listagem

1. Na Page1 do Visual Designer, clique duas vezes no botão Enviar para abrir o método de ação no editor de Java.

2. Adicione o seguinte código de manipulador de eventos em negrito ao método button1_action().

   Observação: Após inserir o código, você pode pressionar Ctrl-Shift-F para reformatar o código automaticamente.

   Amostra de código 2: Manipulador de eventos do Botão1

   public String button1_action() { // Obter as seleções atuais do SessionBean1 String[] mySelections = getSessionBean1().getChoices(); String showSelections = ""; if (mySelections != null) { // Criar uma lista dos valores dos itens selecionados for (int i = 0; i < mySelections.length; i++) showSelections = showSelections + mySelections[i] +"\n"; } if (showSelections.equals("")) showSelections = "nada selecionado"; else showSelections = "Valores selecionados:\n" + showSelections; // Exibir a lista em textArea1 getTextArea1().setValue(showSelections); return null; }

3. Clique na seta verde na barra de ferramentas principal ou escolha Executar > Executar projeto principal, para construir e executar o aplicativo.

4. No aplicativo em execução, selecione um ou mais itens na caixa de listagem e clique no botão Enviar.

   Para selecionar vários itens, use Control+clique. Quando você clicar no botão Enviar, os valores dos itens selecionados são exibidos na área de texto. A Figura 4 ilustra o aplicativo em execução.

   Figura 4: Aplicativo da caixa de listagem em execução no navegador

Adicionando e removendo os itens da caixa de listagem

1. Clique em Design para abrir o Visual Designer.
2. Adicione um botão abaixo do botão Enviar. Altere o texto do botão para Adicionar.
3. Adicione um segundo botão abaixo do botão Adicionar. Altere o texto do botão para Remover.

4. Clique duas vezes no botão Adicionar e insira o seguinte código em negrito no método button2_action.

   Amostra de código 3: Método de ação do Botão2

   public String button2_action() { // Adicionar um item garantido ao componente listbox1 getSessionBean1().addOption(); getTextArea1().setText("Novo item adicionado"); return null; }

   
   Observação: Seu código apresentará um erro na linha em getSessionBean1().addOption() porque tal método ainda não foi adicionado ao Bean de sessão. Devido a esta condição de erro, você não poderá usar a exibição Design, motivo pelo qual você usa a janela Esboço na próxima etapa.
5. Abra a janela Esboço e, em seguida, clique com o botão direito do mouse no nó button3:Remove e selecione Editar manipulador de eventos de.

6. Adicione o código em negrito abaixo ao método button3_action().

   Amostra de código 4: Método de ação do Botão3

   public String button3_action() { // Remover o item ou itens selecionados getSessionBean1().removeOptions((String[])getListbox1().getSelected()); getTextArea1().setText("Itens selecionados removidos"); return null; }

   
   Observação: Seu código apresentará um erro na linha que começa com getSessionBean1().removeOption() porque tal método ainda não foi adicionado ao Bean de sessão.
7. Na janela Esboço, clique com o botão direito do mouse no SessionBean1 e escolha Adicionar > Propriedade.
8. Na caixa de diálogo Novo padrão de propriedade, defina o Nome como counter e o Tipo como int, em seguida, clique em OK para adicionar a nova propriedade.
9. Na janela Esboço, clique duas vezes em SessionBean1 para abrir seu código-fonte no editor de Java.

10. No construtor SessionBean1, inicialize o contador inserindo a seguinte linha após
    choices = new String[] {};

       counter = 0;

11. Insira os métodos seguintes após o construtor SessionBean1.

    Amostra de código 5: Métodos addOption e removeOptions

    public void addOption() { // Adicionar um novo item à lista criando uma // matriz atualizada que contenha o novo item setCounter(getCounter() + 1); // contador para garantir valores exclusivos String newItemVal = "newitem" + getCounter(); Option opt = new Option(newItemVal, "Novo item " + getCounter()); Option[] current = getListOptions(); Option[] newOpts = new Option[current.length + 1]; // adicionar os itens atuais à nova matriz for (int i = 0; i < current.length; i++) newOpts[i] = current[i]; newOpts[current.length] = opt; setListOptions(newOpts); // atualizar a lista setChoices(new String[] {newItemVal}); // selecionar o novo item } public void removeOptions(String[] selectedValues) { // Remover as opções que estão selecionadas na // lista fazendo com que os valores correspondam com as opções Option[] current = getListOptions(); int curLength = current.length; if (selectedValues != null) { int numSelected = selectedValues.length; int newLength = curLength - numSelected; Option[] newOpts = new Option[newLength]; // matriz da lista atualizada int k = 0; // contador da lista atualizada boolean found = false; for (int i = 0; i < current.length; i++) { // examinar os itens atuais para identificar aqueles que serão removidos found = false; for (int j = 0; j < numSelected; j++) { if (current[i].getValue().equals(selectedValues[j])) { // este item será removido found = true; break; } } if (!found) { // visto que este item não foi selecionado, adicioná-lo à lista atualizada newOpts[k] = current[i]; k++; } } setListOptions(newOpts); // atualizar a lista setChoices(null); // remover os valores selecionados existentes } }

12. Agora que os novos métodos foram adicionados ao Bean de sessão, clique na guia Page1.jsp para abrir esta página e clique no botão Design para voltar ao Visual Designer.

    A condição de erro ainda está sendo exibida na página.
13. Clique no botão Atualizar na barra de ferramentas do Visual Designer para remover a condição de erro e exibir os componentes na página.

14. Execute o aplicativo.

    Para testar o novo código, clique no botão Adicionar para adicionar um novo item ao final da lista, como mostrado na Figura 5. Para remover um ou mais itens, selecione os itens e clique no botão Remover.

    Figura 5: Adicionando um item à caixa de listagem

Consulte também:

• Examinando componentes
• Usando componentes de vinculação de dados para acessar um banco de dados