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.

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

 

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.