Skip to end of metadata
Go to start of metadata

Conteúdo

Introdução

Este pacote fornece mecanismos para a a confecção de um wizard (ou assistente). Este assistente pode ser usado para a obtenção de dados do usuário para a posterior execução de um conjunto de ações. A obtenção destes dados é tipicamente dividida em passos que facilitam o entendimento e a construção da parametrização daquilo que será executado em seguida. A figura abaixo ilustra um diálogo simplificado com dois passos de execução.

Conceitos

Neste pacote, é importante ter em mente como ele funciona. Caso contrário, o desenvolvedor pode se enganar na forma de implementar sua aplicação. Existem três conceitos fundamentais:

  1. o step;
  2. o wizard;
  3. o history;

O Step (Passo)

Conforme descrito anteriormente, a parametrização do assistente é dividida em passos. O conceito de passo é fundamental para o programador e se manifesta, no código, em objetos cuja classe implementa seu comportamento lógico e visual. Em outras palavras, o desenvolvedor deve implementar subclasses de Step para cada passo do seu wizard.

class MyStepA extends Step {
  // Elementos de um passo A do wizard.
}
 
class MyStepB extends Step {
  // Elementos de um passo B do wizard.
}

 

Dentro do step, são colocados elementos de interface responsáveis pela aquisição dos dados do usuário. Estes widgets são agrupados, normalmente, dentro de um painel (JPanel). 

Em conjunto com os elementos da IHC, existem dois métodos notifyChanged() e isReady() que controlam o relacionamento dos widgets com o wizard.

  • isReady() informa se todos os widgets obrigatórios de sua interface gráfica já estão preenchidos.
  • notifyChanged() é o método que você utiliza para informar ao wizard que ocorreu uma modificação na sua interface gráfica. Existem algumas implementações de listeners do Swing que já chamam este método. Você deve preferencialmente utilizar um desses listeners (apenas para evitar duplicação de código). Eles são simples e, na prática, eles invocam o notifyChanged quando são chamados.

A chamada do notifyChanged() poderá alterar o estado de diversos widgets do wizard, como os botões Confirmar, Cancelar, Fechar, Próximo, etc. Depois de um notifyChanged(), o wizard irá chamar uma bateria de métodos canXXX() para verificar o que o passo pode fazer, atualizando sua interface gráfica adequadamente.

 

Outros Métodos

  • enter(): Este método é chamado pelo wizard toda vez que o passo se torna passo corrente, ou seja, que ele entra. Neste método você preencherá as informações iniciais dos seus widgets. Essas informações podem: estar no history, ser processadas com base no history ou ser adquiridas externamente ao wizard (ex.: uma consulta ao sistema de arquivos).
  • exit(): Este método é chamado pelo wizard toda vez que o passo deixa de ser o passo corrente, ou seja, que ele sai. Neste método você coletará as informações dos seus widgets e atualizará o history.
  • canGoNext(): Este método é chamado pelo wizard quando ele precisar saber se pode ou não habilitar o botão de next
  • getNext(): Este método é chamado pelo wizard quando ele avança de passo corrente. O step implementa este método para informar qual é o próximo passo (ou null). 
  • canGoPrevious(): Este método é chamado pelo wizard quando ele precisar saber se pode ou não habilitar o botão de previous
  • canCancel(): Deve ser implementado para informar se o passo permite cancelamento.
  • cancel(): É chamando no passo corrente quando o botão de cancelar do wizard é acionado. Sobrescreva se quiser alguma ação específica.
  • canConfirm(): Deve ser implementado para informar se o passo permite confirmação. Apenas passos que executam alterações no sistema, confirmam.
  • confirm(): é chamando no passo corrente quando o botão de confirmar do Wizard é usado. Sobrescreva com a ação desejada nos passos que aceitem confirmação. O método confirm é a "razão de ser" do wizard.
  • canClose():  deve ser implementado para informar se o passo permite que o wizard pode ser fechado.
  • close():  é chamado no passo corrente quando o wizard é fechado. Sobrescreva se quiser alguma ação específica. Note que este método difere do confirm(). Logo, não altere o estado do sistema!

 

Não execute ações que provoquem efeitos que alterem o estado do sistema fora do método confirm().

Observe que você pode executar qualquer tipo de ação com a intenção de obter dados, como acessar a rede, banco de dados, etc nos diversos métodos do step. A ideia do wizard é coletar informações passo a passo e executar as operações apenas no confirm(). E, para isso, o confirm() recebe o history como parâmetro.

Lembre-se que passos intermediários podem ter confirm(). E o confirm() não fecha o wizard!

O Wizard (Assistente)

Este conceito modela o assistente como um todo e é suportado pela classe Wizard.

O assistente é implementado com objetos (da classe Wizard) que controlam todo o seu funcionamento. O wizard sempre possui um passo corrente e chama os métodos desse passo em momentos específicos. A construção do wizard é feita, pela aplicação, com a montagem dos diversos passos (steps) que representam a sequência de interações desejadas.

 

class MyWizardFrame extends JFrame {
 
 private Wizard wizard;
 
 private MyWizardFrame() {
    super("Título do Wizard");
    this.wizard = buildWizard(); 
    
    this.getContentPane().add(wizard);
    this.pack();
  }
 
  private Wizard buildWizard() {
    // Montagem dos passos (steps) do assistente.
    Wizard wiz = new Wizard(...);
    (...)
    return wiz;
  }
 
  // Main
  public static void main(String[] args) {
    MyWizardFrame frame = new MyWizardFrame();
    frame.setVisible(true);
  }
}

Montagem de Passos

@@Métodos para montagem do wizard.

@@StepGroup

O History (Histórico)

É o único lugar aonde o desenvolvedor deve guardar estados. Ortodoxamente, procura-se não guardar estados nos widgets e nem em atributos do step. E, com isso, o step costuma não ter atributos, apenas métodos. São estes métodos que precisam consultar ou atualizar o history; que o recebem o parâmetro.

Não guarde o history como atributo do seu passo.

Se você estiver precisando consultar ou alterar o history em um método que não o recebe, é provável que tenha havido mal entendimento quanto ao funcionamento do pacote.

 

@@ Métodos para armazenamento

 

Dúvidas Frequentes (FAQ)

P: É razoável fazer passos com efeito colateral?

R: 

 

 

Créditos

Originalmente, o pacote foi escrito dor Leandro Moreira Pinto e Rodrigo Carneiro. Ao longo de alguns anos, o código evoluiu conforme a necessidade de manutenção do grupo de sistemas distribuídos.

 

  • No labels
Write a comment…