Form e Field · João Carlos Serrenho Dias Pereira
As classes Form e Field
A leitura de dados inseridos pelo utilizador, para definir pesquisas ou criar objectos, por exemplo, é realizada através do conceito de formulário. Um formulário é representado pela classe Form. Um formulário agrupa diversos pedidos de informação numa única interacção.
Cada pedido é constituído por uma cadeia de caracteres e guarda a resposta do utilizador. Relativamente à informação pedida ao utilizador, são suportados 4 tipos: inteiros, reais, boleanos e cadeias de caracteres. Os pedidos são representados pela classe abstracta e genérica Field<T>. Para cada pedido deve ser criada uma instância de FieldInteger, FieldReal, FieldBoolean ou FieldString, dependendo do tipo de dados que o utilizador deve preencher. Cada uma destas classes tem um construtor com um argumento: a mensagem descritiva do pedido a apresentar ao utilizador quando se pedir ao utilizador para inserir uma determinada informação. Existe ainda um quinto tipo de Field, o FieldNone. Este tipo especial de Filed representa um separador entre dois conjuntos de opções do formulário. Este tipo de Field não tem qualquer pedido de informação associado e apenas tem impacto visual.
As classes que representam os diferentes tipos existentes de pedidos não são classes públicas (com excepção do caso FieldNone) e apenas estão disponíveis no package pt.tecnico.uilib.forms. O programador da aplicação não pode por isso utilizar directamente estas classes. Assim, cada pedido associado a um formulário é adicionado ao formulário através de um conjunto de métodos presentes na classe Form:
public void addBooleanField(String key, String label)- para pedir um valor boleano;
public void addStringField(String key, String label)-- para pedir uma cadeia de caracteres;
public void addRealField(String key, String label)-- para pedir um número real;
public void addIntegerField(String key, String label)- - para pedir um número inteiro.
O método a utilizar depende do tipo de dados que se quer pedir ao utilizador. Por exemplo, caso o utilizador tenha que indicar um número inteiro, deve ser utilizado o método addIntegerField. Estes 4 métodos têm todos os mesmos dois argumentos: uma chave única no contexto do formulário (key) e uma mensagem (label) a apresentar ao utilizador para ele inserir a informação pedida. A chave é uma cadeia de caracteres que deve representar de forma única o pedido no formulário em causa. A adição de um novo campo do formulário com uma chave repetida é abortada com uma excepção.
Para preencher um formulário deve ser executado o método parse() sobre o formulário. A execução deste método, processa os vários pedidos do formulário de forma sequencial. Para cada pedido, o formulário apresenta a mensagem associada ao pedido e lê a resposta do utilizador, a qual é guardada no pedido. Caso o utilizador dê uma resposta inválida (por exemplo, quer-se ler um número e o utilizador inseriu uma cadeia de caracteres que não representa um número), a pergunta é repetida e é dada uma nova oportunidade ao utilizador para inserir novos dados. Após o formulário ter sido totalmente prenchido pode-se aceder ao valor recolhido para cada pedido utilizando a chave que identifica o pedido em causa e invocando um dos seguintes métodos sobre o formulário em causa:
public Boolean boleanField(String key) para obter um valor boleano inserido pelo utilizador;
public String stringField(String key) para obter uma cadeia de caracteres inserida pelo utilizador;
public Double realField(String key) para um número real inserido pelo utilizador;
public Integer integerField(String key) para obter um número inteiro inserido pelo utilizador.
O parâmetro destes métodos representa o identificador do pedido em causa.
O exemplo seguinte apresenta a criação de um formulário com 4 campos (perguntas) e a execução deste formulário. É ainda utilizado um separador para separar os 2 primeiros pedidos dos restantes dois.
public final void execute() throws CommandException {
form.addIntegerField("id", "Introduza um valor inteiro");
form.addRealField("real", "Distância");
form.add(new FieldNone("-----"));
form.addStringField("str", "Nome");
form.addBooleanField("sn", "OK?");
Note-se que só depois de executar o método parse() sobre o formulário criado e inicializado é que este é apresentado ao utilizador. Para aceder aos valores inseridos pelo utilizador deve-se um dos 4 métodos de acesso disponibilizados na classe Form indicando o identificador do campo em causa. Por exemplo, para aceder ao valor introduzido pelo utilizador referente ao campo com o identificador "id" deve ser invocado o método integerField("id") sobre o formulário.
No caso particular de um formulário com apenas um único pedido e que apenas é utilizado uma única vez, a classe Form oferece um conjunto de 4 métodos estáticos que criam o formulário, fazem o pedido e devolvem o valor inserido pelo utilizador. O método a utilizar depende do tipo de dados que deve ser inserido pelo utilizador mas todos recebem o mesmo argumento, a pergunta a realizar ao utilizador:
public static Boolean confirm(String prompt) para obter um valor boleano inserido pelo utilizador;
public static String requestString(String prompt) para obter uma cadeia de caracteres inserida pelo utilizador;
public static Double requestReal(String prompt) para um número real inserido pelo utilizador;
public static Integer requestInteger(String prompt) para obter um número inteiro inserido pelo utilizador.