Você vê a janela Propriedades de um componente Caixa de listagem quando seleciona o componente em uma página que está editando no Visual Designer.
Este componente JavaServer Faces 1.2 possui as propriedades a seguir.
Geral
id. Tipo: String
O nome do componente no bean de página e o arquivo JSP. No arquivo JSP, este nome é o valor do atributo id do componente. No bean de página, o valor desta propriedade é o nome do objeto HtmlSelectOneListbox.
Aparência
label. Tipo: String
Se o texto for especificado para esta propriedade, será exibido um rótulo mostrando o texto com o componente.
A propriedade label não é tão flexível quanto o componente Rótulo. Você pode usar o componente Rótulo se quiser ter mais controle sobre a aparência do rótulo, tal como o seu posicionamento em relação ao componente.
labelLevel. Tipo: int
Um número que afeta a aparência do rótulo. 1 (Forte) é grande e em negrito. 2 (Médio), o padrão, é menor e em negrito. 3 (Fraco), é menor e normal (não está em negrito). Esta propriedade tem efeito somente se a propriedade label estiver definida.
labelOnTop. Tipo: booleano
Se esta propriedade for selecionada, o rótulo será renderizado acima do componente. Por padrão, a propriedade não é selecionada e o rótulo é renderizado ao lado do componente.
monospace. Tipo: boolean
Se esta propriedade for selecionada, o rótulo será renderizado em uma fonte monoespaçada.
rows. Tipo: int
O número de opções a serem mostradas de cada vez, 12 opções por padrão. Se houver mais opções a serem mostradas do que indicado nesta propriedade, será adicionada uma barra de rolagem na caixa de listagem. Se esta propriedade não for definida, todas as opções serão exibidas.
separators. Tipo: booleano
Se esta propriedade for selecionada, cada grupo de opções na lista será separado dos outros grupos de opções com um separador visível. Para que os separadores sejam exibidos, as opções da lista devem ser definidas como subclasses da classe com.sun.webui.jsf.model.OptionGroup. Esta propriedade é selecionada por padrão.
style. Tipo: String
Regras de folha de estilo em cascata (CSS nível 2) a serem aplicadas ao componente. Por exemplo:
position: absolute; left: 288px; top: 312px
Você pode inserir valores diretamente ou clicar no botão de reticências (...) para usar o Editor de estilo.
Esta propriedade substitui quaisquer configurações do tema ou do arquivo CSS desse componente. Se um estilo especificado nesta propriedade não surtir efeito, é porque uma área do componente está obscurecida por um componente filho que possui configurações de estilo diferentes.
Para obter uma lista de estilos CSS2, consulte a página da Web em
styleClass. Tipo: String Uma lista separada por espaços de classes de estilo CSS2 a serem aplicadas quando o componente é renderizado. As classes de estilo devem ser definidas na folha de estilo do projeto no arquivo CSS do tema. Se você clicar no botão de reticências (...), verá uma lista de todos os estilos que podem ser adicionados a esta propriedade. Para obter informações sobre a adição de classes CSS e regras na folha de estilos em cascata do projeto, consulte Editor CSS.
Consulte a observação acima abaixo da descrição da propriedade style para obter uma explicação do porquê uma classe adicionada a esta propriedade talvez pareça não ter efeito no componente.
Se você adicionar uma classe de estilo CSS a partir do tema atual ao arquivo CSS do projeto e redefinir a classe do estilo, a alteração afetará todos os componentes que usam essa classe de estilo. Entretanto, é possível adicionar suas próprias classes de estilo ao arquivo CSS do projeto que redefine as classes de estilo padrão e, em seguida, quando você adicionar as classes a esta propriedade, as alterações afetarão somente a instância deste componente.
Dados
converter. Tipo: Conversor
Um conversor JavaServer Faces que produz o tipo correto do valor da propriedade value. Se o usuário inserir o tipo incorreto de valor, tal como uma palavra em vez de um número em um Conversor de inteiro, o conversor enviará uma mensagem que você poderá exibir em um componente Mensagem.
Se você usar um conversor de Enum com este componente, deverá editar a declaração Java do conversor para usar uma classe enum como parâmetro, conforme descrito em Conversor de Enum.
items. Tipo: Objeto
Especifica um objeto que fornece os itens para a lista. O IDE cria um objeto padrão quando você adiciona a caixa de listagem na página. Por exemplo, para uma caixa de listagem chamada listBox1, há um objeto listBox1DefaultOptions que o IDE exibe como um nó na janela Navegador. Você pode vincular esta propriedade a um provedor de dados ou um objeto, clicando com o botão direito do mouse no componente e escolhendo Vincular aos dados. Se você vincular a um objeto, o objeto escolhido deverá ser uma matriz, Mapa ou Coleção cujos membros são subclasses de com.sun.webui.jsf.model.Option.
multiple. Tipo: booleano
Indica se o usuário pode ou não selecionar vários itens na lista de uma vez.
required. Tipo: booleano
Se for selecionada, o usuário deverá selecionar um item na lista antes que a página seja enviada. Se você adicionar um componente Mensagem à página e vincular sua propriedade for a este componente, será exibida uma mensagem de erro se o usuário tentar enviar a página sem selecionar um item.
selected. Tipo: Objeto
Seleciona o elemento da lista selecionado no momento e envia-o para o servidor quando a página é enviada. Esta propriedade não controla a lista que é exibida no componente. A lista que é exibida no componente é controlada pela propriedade items, descrita acima. Você pode vincular esta propriedade a um provedor de dados ou objeto, clicando no botão de reticências (...) e usando o editor de propriedade.
validatorExpression. Tipo: MethodExpression
Indica a expressão do validador JavaServer Faces usada quando o valor é enviado. Um validador garante que o valor correto é inserido por um usuário. Se as condições definidas pelo validador não forem atendidas, o validador enviará uma mensagem que você pode exibir em um componente Mensagem.
Escolha um validador na lista suspensa. Se você escolher (null), nenhum validador será chamado. Se você escolher um validador, talvez também queira selecionar a propriedade required para garantir que o usuário insira um valor.
Você pode definir seu próprio método de validação, por exemplo, clicando com o botão direito do mouse no componente e escolhendo Editar manipulador de eventos > Validar. Se você definir o seu próprio método, qualquer valor que tenha definido nesta propriedade será substituído.
Eventos
Defina as propriedades do evento, clicando com o botão direito no mouse no Visual Designer e escolhendo Editar manipulador de eventos > nome do evento.
valueChange. Indica o nome do método ouvinte de alteração de valor do componente que é chamado quando o valor do componente é alterado. Se este método não for definido, o valor desta propriedade será null. Você geralmente define este método no bean de página, clicando com o botão direito do mouse no componente no Visual Designer e escolhendo Editar manipulador de eventos > processValueChange. O nome padrão do método é id-do-componente_processValueChange, onde id-do-componente é o valor da propriedade id do componente.
validate. Indica o nome do método chamado para validar o valor do componente.
Se você deseja codificar um método de validação em vez de escolher um validador JavaServer Faces para a propriedade validatorExpression, clique com o botão direito do mouse no componente e escolha Editar manipulador de eventos > Validar. O nome padrão do método é id-do-componente_validate, onde id-do-componente é o valor da propriedade id do componente. Quando você define este método desta forma, as propriedades validator e validate são definidas automaticamente para você. Se você definir um validador, talvez também queira selecionar a propriedade required para garantir que o usuário insira um valor.
A definição desta propriedade também define o valor da propriedade validatorExpression. Se você definir o seu próprio método de validação, não altere separadamente o valor da propriedade validatorExpression, ou você poderia perder a conexão com o método de validação.
Comportamento
disabled. Tipo: booleano
Se for selecionada, indicará que o componente nunca deverá receber o foco ou ser incluído em um envio. Use esta propriedade quando o componente não se aplicar à página. Consulte a observação abaixo da propriedade readOnly sobre os efeitos do uso da propriedade disabled em comparação ao efeito do uso da propriedade readOnly.
toolTip. Tipo: String
Informações de título consultivo sobre o componente, que podem ser lidas por um leitor de tela e podem ser exibidas como uma dica de ferramenta.
Se o componente for desativado, a dica de ferramenta não será exibida na maioria dos navegadores.
visible. Tipo: booleano
Indica se o componente pode ser visto ou não pelo usuário na página HTML renderizada. Esta propriedade é selecionada por padrão. Se você desmarcar esta propriedade, o código HTML do componente será renderizado na página, mas o componente não ficará visível no navegador porque ele estará oculto por uma configuração de estilo. Como o código HTML é renderizado, o componente ainda pode ser processado em envios de formulário, e os usuários que vêem o código-fonte no navegador podem ver o código HTML. Além disso, sua aplicação Web pode usar JavaScript do lado cliente para mostrar ou ocultar o componente.
Se você precisar ocultar completamente o componente, por exemplo, porque ele contém informações confidenciais que determinados usuários não podem ver, desmarque a propriedade rendered.
Acessibilidade
tabIndex. Tipo: String
Especifica opcionalmente a posição do componente na ordem das guias do documento, determinando quando o componente terá o foco, se o usuário navegar no documento. O valor deve ser um inteiro entre 0 e 32767.
JavaScript
onBlur. Tipo: String
JavaScript a ser executado quando o componente perde o foco.
onChange. Tipo: String
JavaScript a ser executado quando o componente perde o foco e seu valor é modificado depois de ganhar o foco.
onClick. Tipo: String
JavaScript a ser executado quando o usuário clica no componente.
onDblClick. Tipo: String
JavaScript a ser executado quando o usuário clica duas vezes no componente.
onFocus. Tipo: String
JavaScript a ser executado quando o componente recebe o foco.
onKeyDown. Tipo: String
JavaScript a ser executado quando o componente recebe o foco e a tecla é pressionada.
onKeyPress. Tipo: String
JavaScript a ser executado quando o componente recebe o foco e a tecla é pressionada e liberada.
onKeyUp. Tipo: String
JavaScript a ser executado quando o componente recebe o foco e a tecla é liberada.
onMouseDown. Tipo: String
JavaScript a ser executado quando o cursor do mouse está sobre o componente e o usuário pressiona o botão do mouse.
onMouseMove. Tipo: String
JavaScript a ser executado quando o usuário move o cursor do mouse no componente.
onMouseOut. Tipo: String
JavaScript a ser executado quando o usuário move o cursor do mouse para longe do componente, depois de estar sobre o componente.
onMouseOver. Tipo: String
JavaScript a ser executado quando o usuário move o cursor do mouse para o componente.
onMouseUp. Tipo: String
JavaScript a ser executado quando o cursor do mouse está sobre o componente e o usuário libera o botão do mouse.
Avançado
immediate. Tipo: booleano
Se esta propriedade for selecionada, quando o usuário ativar o componente, o código na página será executado antes da validação, atualização de valores do modelo, etc. Finalmente, a execução do código acontece imediatamente no servidor que, em seguida, retorna a página. Uma forma mais simples de obter esta funcionalidade é associar o componente a um formulário virtual e, em seguida, clicar com o botão direito do mouse no componente e escolher Enviar automaticamente ao alterar.
O exemplo mais comum de uma ação imediata é um botão Cancelar. Você pode torná-lo imediato para que a validação normal e as etapas de atualização possam ser ignoradas, mas o manipulador de ações ainda poderá fazer o que for necessário. Geralmente, o manipulador de ações navegará de volta para alguma página anterior. Em alguns designs, o manipulador de ações também pode enfileirar uma mensagem informativa como "Transação cancelada". É possível fazer mais: por exemplo, uma aplicação deve registrar o fato de que o usuário cancelou a operação atual.
rendered. Tipo: booleano
Se for selecionada, o componente será renderizado e processado em qualquer envio de página subseqüente. Se não for selecionada, o componente não aparecerá na página, nem mesmo como um componente oculto. Se você quiser que o componente fique oculto mas que seja processado quando a página for enviada, desmarque a propriedade visible em vez desta propriedade.
Você pode vincular esta propriedade a uma propriedade JavaBeans que determina quando o componente é renderizado. Por exemplo, um formulário de reserva de viagens pode mostrar um componente para passageiros freqüentes e não mostrá-lo para o público em geral. Para vincular esta propriedade, clique no botão de reticências (...) à direita da propriedade e escolha Usar vinculação na caixa de diálogo.