Tivoli Service Desk 6.0 Developer's Toolkit Script - Guia de Programação

Capítulo 7: O Sistema de Formulário

Retornar ao Índice


Introdução

Definição

O TSD Script oferece um sistema de formulário que é usado para criar janelas a partir de um arquivo de descrições (recursos).

Um formulário é uma janela que contém algum tipo de forma de entrada de dados. Em um ambiente de interface com o usuário (GUI), o formulário é o meio principal de interação entre o usuário e o aplicativo. O desenvolvedor coloca os controles no formulário em branco selecionando-os a partir de uma barra de ferramentas. Os controles de formulário incluem:

Controles de formulários

Um controle de formulário é um elemento que é usado para obter informações do usuário ou para transportar informações para o usuário. Por exemplo, um formulário de entrada de dados geralmente contém um ou mais controles de caixa de texto, um botão OK e um botão Cancelar. O Criador de Interface do Developer's Toolkit pode ser usado para incluir controles em um formulário (consulte o Tivoli Service Desk 6.0 Developer's Toolkit - Guia do Criador de Interface para obter informações adicionais).

A lista a seguir inclui todos os controles de formulário aceitos pelo TSD Script.

Nome do Controle Descrição
Subformulário Controle complexo que contém vários outros controles.
Caixa de texto Área retangular que permite que o usuário digite uma única linha de informação. Se o texto que o usuário digitar não couber em uma única linha, a caixa rolará automaticamente.
Caixa de texto multilinha Área retangular usada para digitar várias linhas de texto. Opcionalmente, pode haver quebra de linha do texto dentro da caixa.
Quadro de listagem Caixa retangular que contém uma lista de opções possíveis. Os usuários não podem digitar uma seleção em um quadro de listagem.
Caixa de combinação Caixa de texto com um quadro de listagem anexado. O usuário pode digitar um valor na caixa de texto ou selecionar ou validar na lista sobreposta. O valor selecionado aparece na caixa de texto e o quadro de listagem desaparece.
Árvore Controle que exibe dados hierárquicos.
Botões de rádio Botão usado para selecionar uma opção a partir de um conjunto de opções mutuamente exclusivas. Os usuários selecionam um botão; em seguida, esse botão é preenchido.
Caixa de opções Caixas quadradas cujas opções podem ser selecionadas ou desmarcadas para ativar ou desativar uma opção. Mais de uma caixa de opções pode ser selecionada por vez.
Régua de controle Uma barra que move interativamente.
Botão Botão retangular que inicia uma ação.
Texto Campo que exibe texto. Os usuários não podem modificar o texto.
Relógio Um relógio com a hora do dia em execução ou um contador de tempo decorrido.
Tabela Dados estruturados em linhas e colunas.
Hipertexto Área que exibe o texto em um formato hipertexto.
Caixa de grupo Uma estrutura retangular que agrupa vários controles por significado ou funcionalidade.
Imagem Campo que exibe uma imagem de um arquivo.

Arquivos de formulários

Os formulários são mantidos como recursos de aplicativo separados. O Developer's Toolkit permite que você crie uma coleção de especificações de formulário e armazene-as em arquivos com uma extensão .df. Como arquivos de base de informações (.kb), há um formulário de origem e um formulário de objetos para tais especificações. Um arquivo .df permite menus, barras de ferramentas e cadeias.

O Gerador de Interface é um programa de TSD Script que obtém um arquivo .df de origem e cria um arquivo .dfc de objetos. Os arquivos .dfc são carregados e exibidos pelo Developer's Toolkit em tempo de execução.

Amostra de código de formulário

O exemplo a seguir de um fragmento de código TSD Script usa um formulário.

  TYPES 
    EmployeeRecord IS RECORD 
      first, last, ssn : STRING; 
      salary : REAL; 
      department : STRING; 
     END; 
   VARIABLES 
      employee: EmployeeRecord; 
   ACTIONS 
  IF DlgBox($Desktop,'EMPLOYEE.DFC[ADDFORM]',
            $NullHandler,employee) > 0 THEN 
        SQLInsert('EMPLOYEES',employee); 
     END; 

No exemplo, um novo tipo EmployeeRecord foi declarado na seção types. Na seção variables, há também uma variável deste tipo. Nomes de campo de registro são o mesmo de nomes de controle de formulário.

A instrução DlgBox na seção actions faz o seguinte:

Os formulários geralmente também contêm os botões OK e Cancelar.

Argumentos da instrução DlgBox

A instrução DlgBox possui quatro argumentos:

Título do argumento Descrição
Parent Window O identificador para a janela principal do novo formulário.
Form File O nome de um arquivo de especificações de formulário compilado. Se o arquivo tiver mais de uma especificação de formulário, o nome
do formulário desejado deverá estar entre colchetes após o nome do arquivo.
Event Handler Do mesmo modo que as janelas genéricas discutidas anteriormente, todos os formulários possuem uma rotina de tratamento de eventos associada a eles.

Algumas vezes, você pode querer que a rotina de tratamento execute a ação padrão para cada evento. Se assim for, você pode
especificar $NullHandler. Neste caso, $NullHandler permite que o usuário se mova de um controle de formulário a outro
e digite valores no formulário.

Quando o usuário escolhe um botão com a propriedade Aceitar, o TSD Script copia automaticamente o conteúdo dos controles do formulário para os
campos correspondentes na variável de resultado.

Result Variable Uma variável de registro cujos campos correspondem aos controles no formulário.

Quando um usuário sai de um formulário pressionando um botão com a propriedade Aceitar, o conteúdo de cada controle no formulário é copiado para
os campos correspondentes da variável de registro. A variável de registro pode, então, ser gravada em um banco de dados, exibida
em uma janela ou qualquer coisa que seja apropriada para o aplicativo.

Exemplo do DlgBox

Considere um outro exemplo:

  TYPES 
    EmployeeRecord IS RECORD 
      first, last, ssn : STRING; 
      salary : REAL; 
      department : STRING; 
     END; 
   VARIABLES 
      employee: EmployeeRecord; 
   ACTIONS 
  SQLSelectInto('SELECT * FROM EMPLOYEES WHERE 
              SSN=305-33-4111',employee); 
  IF DlgBox($Desktop,'EMPLOYEE.DFC[EDITFORM]',
            $NullHandler{employee},employee) >> 0 THEN 
    SQLUpdate('EMPLOYEES','WHERE SSN=''' & 
            employee.snn & '''',employee); 
     END; 

Este exemplo mostra o código que:

Foram feitas duas alterações a esta instrução DlgBox:

No exemplo, o usuário vê as informações recuperadas da tabela EMPLOYEES no formulário e pode mover-se para qualquer formulário e alterar quaisquer informações.

Rotinas de Tratamento de Eventos de Formulário

Para tratar de recursos avançados, como exibir a foto de um funcionário quando o usuário escolhe um botão ou validar o formato de um número de carteira de trabalho, você deve usar uma rotina de tratamento de eventos. Para fazer isto, é necessário criar rotinas de tratamento de eventos de formulário.

Exemplo de rotina de tratamento de eventos

Esta seção apresenta um formulário com uma rotina de tratamento de eventos. O exemplo apresenta uma base de informações inteira chamada Employees que implementa uma função pública única chamada AddEmployee. O corpo de AddEmployee é semelhante aos exemplos anteriores, exceto que em vez de utilizar $NullHandler, é feita referência a uma rotina de tratamento de eventos chamada EmployeeEvent.

KNOWLEDGEBASE Employees; 
  USES 
  Globals; 
  TYPES
    EmployeeRecord IS RECORD 
      first, last, ssn : STRING; 
      salary : REAL; 
      department : STRING; 
     END; 
    ROUTINES 
    FUNCTION AddEmployee: BOOLEAN; 
PRIVATE 
    ROUTINES 
    EVENT EmployeeEvent(REF employee: 
                        EmployeeRecord) IS 
    ROUTINES
      FUNCTION ValidSSN(VAL ssn: STRING): BOOLEAN IS 
   VARIABLES 
        i: INTEGER; 
   ACTIONS 
        IF StrLength(ssn) <> 11 THEN 
        EXIT(FALSE); 
     END; 
        FOR i:=1 TO 11 DO 
          IF (i = 4 OR i = 7) AND (ssn[i] <> '-') THEN 
        EXIT(FALSE); 
          ELSIF StrPos('0123456789',ssn[i]) = 0 THEN 
        EXIT(FALSE); 
     END; 
     END; 
        EXIT(TRUE); 
      END (* SSN Válido *);
       ACTIONS 
WHEN $Event IS $MsgSelect THEN 
        WHEN $FieldName IS 'SSN' THEN 
          IF NOT ValidSSN(employee.ssn) THEN 
            Exit(0); 
     END; 
        ELSWHEN 'PICTURE_BUTTON' THEN 
          ShowPicture(employee.last_name & '.BMP'); 
     END; 
     END; 
    END (* Evento Employee *);
    FUNCTION AddEmployee: BOOLEAN IS 
   VARIABLES 
      employee: EmployeeRecord; 
   ACTIONS 
      IF DlgBox(mainWindow, 'EMPLOYEE.DFC[ADDFORM]',
                EmployeeEvent{employee},employee) > 0 THEN 
        SQLInsert('EMPLOYEES',employee); 
        EXIT(TRUE); 
      ELSE 
        EXIT(FALSE); 
     END; 
    END (* Insere Funcionário *); 

EmployeeEvent é uma rotina de tratamento de eventos que possui um único parâmetro de passagem por referência do mesmo tipo da variável de retorno passada em DlgBox.

A rotina de tratamento de eventos testa somente um evento, $MsgSelect, e é gerada sempre que o formulário está prestes a mover o cursor para fora do controle atual.

Se o usuário digita um valor em um controle de texto e pressiona a tecla TAB, um evento $MsgSelect é gerado. O nome do controle que o usuário está prestes a deixar vem junto com este evento em um parâmetro "invisível" chamado $FieldName.

O próximo exemplo aparece mais exatamente no corpo de EmployeeEvent.

WHEN $Event IS $MsgSelect THEN 
        WHEN $FieldName IS 'SSN' THEN 
          IF NOT ValidSSN(employee.ssn) THEN 
            Exit(0); 
     END; 
        ELSWHEN 'PICTURE_BUTTON' THEN 
          ShowPicture(employee.last_name & '.BMP'); 
     END; 
     END; 

Este exemplo ilustra o seguinte:

O resultado padrão é "1,", indicando sucesso. No entanto, há casos em que é necessário retornar um valor diferente.

O Evento $MsgSelect

Certos eventos gerados automaticamente pelo TSD Script são recusados quando a rotina de tratamento é abandonada com um valor 0. $MsgSelect é um evento desse tipo.

Se EmployeeEvent constata que um número de carteira de trabalho inválido foi fornecido ao processar o evento $MsgSelect para o campo SSN, ele abandona com um valor 0.

Esta ocorrência é conhecida como recusar o evento. O resultado desta recusa é duplicado.

Como gerar um evento $MsgSelect

Geralmente, o evento $MsgSelect permite que você saiba que algo foi alterado em um formulário. $MsgSelect pode ser gerado de um dos seguintes modos:

Nota: $MsgSelect é gerado somente quando um novo valor é diferente do antigo.

Nota: Pressionar ENTER é o mesmo que escolher o botão de comando padrão, se algum tiver sido definido. Isso gera um evento $MsgAccept. Se não houver um botão de comando padrão, será gerado um evento $MsgSelect.

Quando a rotina de tratamento de eventos recebe o evento $MsgSelect, os dados de ocorrência da janela (que a rotina de tratamento faz referência com seu argumento de registro) são atualizados para refletir a alteração. Por exemplo, quando um usuário digita um valor na caixa de texto SSN e pressiona a tecla TAB, o valor é copiado para o campo SSN da variável de ocorrência da janela e um evento $MsgSelect é gerado. O valor do campo anterior está disponível no primeiro parâmetro de evento sem nome.

O valor do controle não é definido até que a mensagem Select seja concluída; portanto, o valor de controle não pode ser consultado.

Outros Eventos do Formulário

Os formulários podem gerar uma série de outros eventos, incluindo:

Eventos de Formulário Descrição
$MsgInitialize Versão especial do $MsgSelect que ocorre somente durante a fase de criação de um formulário.
$MsgCreate Recebido quase antes do formulário ser exibido. Este é um bom momento para executar inicializações, como incluir
a lista de opções possíveis em um quadro de listagem e etc.
$MsgDestroy Recebido quase antes de um formulário ser fechado.
$MsgAccept Recebido quando o usuário aceita um formulário, geralmente pressionando ENTER ou escolhendo OK.
$MsgCancel Recebido quando o usuário cancela um formulário, geralmente pressionando ESCAPE ou escolhendo Cancelar.
$MsgEnterField Recebido quando o cursor está prestes a especificar um novo controle. $FieldName contém o nome do
novo controle.
$MsgExitField Recebido quando o cursor está prestes a deixar um controle. $FieldName contém o nome desse controle.
$MsgHelp Recebido quando o usuário escolhe Auxílio ou a tecla F1.
$MsgMandField Recebido quando o usuário tenta aceitar um formulário com uma ou mais caixas de entrada de texto obrigatórias não preenchidas.

$FieldName contém o nome da primeira caixa de entrada de texto obrigatória em branco. Por padrão, o sistema exibe
uma mensagem notificando o problema ao usuário. Retorne 0 para evitar que esta caixa seja exibida.

Nomes de Controles de Formulários

Cada controle em um formulário possui um nome. Em exemplos anteriores, foi utilizado um formulário para obter as informações necessárias para preencher um variável do tipo EmployeeRecord. Como esse registro tem um campo chamado FIRST_NAME, um controle de formulário chamado FIRST_NAME também é necessário. Quando um usuário digita um valor no controle de formulário FIRST_NAME, as informações são copiadas para o campo de registro FIRST_NAME.

Nota: Alguns controles não transportam dados. Por exemplo, botões de comando não tem um valor; eles geram eventos. Portanto, você não precisa ter um campo de registro para nenhum botão em um formulário.

Atributos de controle adicionais

Você pode especificar atributos adicionais para controles de formulário, incluindo:

Atributos Descrição
Read Only Os dados no controle são inicializados pelo registro de ocorrência da janela e não podem ser alterados pelo usuário.
Mandatory O usuário não pode aceitar o formulário até que tenham sido fornecidos os valores para todos os controles obrigatórios.
Input Length Especifica o número de caracteres que o usuário pode digitar para o controle em um campo de texto.

Há outros atributos que afetam apenas controles específicos. Por exemplo, você pode ativar ou desativar a quebra de linha para caixas de texto multilinha.

Table

Descrição

Table é uma janela usada para exibir uma tabela de resultados de SQL. Uma tabela de resultados de SQL é um conjunto de linhas e colunas.

Table é usada como um controle de formulário e permite:

As colunas dentro de Table são redimensionáveis. Uma barra vertical fina separa as colunas adjacentes e os usuários podem reposicionar esta barra para alterar a largura da coluna.

A instrução select pode ser especificada no arquivo .df ou de modo programático.

Instruções Descrição
DlgSQLSelect Esta instrução faz com que o TSD Script emita a consulta SQL indicada e atualize o conteúdo do controle indicado Table com os resultados dessa consulta.

Esta instrução possui três argumentos:

  • O identificador de janela do formulário
  • O nome do controle Table
  • Uma expressão de cadeia representando uma instrução SQLSelect

Este é o modo mais eficiente para obter dados de um banco de dados para um controle table.

DlgFieldValue Esta instrução pode ser usada para recuperar uma linha selecionada.
Esta instrução possui três argumentos:
  • o identificador de janela do formulário
  • o nome do controle
  • uma variável de registro que recebe informações da linha destacada

As colunas da linha são copiadas para os campos de registro que têm nomes idênticos (por exemplo, a coluna "FIRST_NAME" é copiada para r.FIRST_NAME).

DlgListBoxInsert Esta instrução insere uma nova linha em Table. Este comando não executa uma instrução SQLInsert, mas inclui uma nova linha ao controle de formulário indicado.

Esta instrução possui três argumentos:

  • O identificador de janela do formulário
  • O nome do controle
  • Uma variável de registro cujos campos devem corresponder aos nomes de coluna de Table

Os valores correspondentes são copiados para as colunas apropriadas e os campos de registro sem correspondências de coluna são ignorados.

DlgListBoxUpdate Esta instrução atualiza uma linha selecionada em Table. Este comando não executa uma instrução SQLUpdate, mas atualiza as informações no formulário.

Esta instrução possui três argumentos:

  • O identificador de janela do formulário
  • O nome do controle
  • Uma variável de registro cujos campos são correspondidos com nomes de coluna do controle Table

Os valores correspondentes são copiados para as colunas apropriadas. Os campos de registro sem correspondências de coluna são ignorados.

DlgListBoxDelete Esta instrução elimina a linha selecionada no controle Table. Este comando não executa uma operação SQLDelete, mas remove uma linha do controle indicado na janela do formulário.

Esta instrução possui dois argumentos:

  • O identificador de janela do formulário
  • O nome do controle Table

Exemplo de Table

Este exemplo cria uma base de informações chamada Users com um único procedimento público chamado WorkWithUsers.

KNOWLEDGEBASE Users; 
  TYPES
    UserRecord IS RECORD 
      $Select : String; 
      user_ID : String; 
      user_name : String; 
      user_rights : Integer; 
     END; 
    ROUTINES 
    PROCEDURE WorkWithUsers; 
PRIVATE 
    ROUTINES 
    EVENT UserEvent(REF user: UserRecord) IS; 
   VARIABLES 
      i: Integer; 
    ROUTINES
      PROCEDURE AddUser IS; 
   VARIABLES 
        newUser: UserRecord; 
   ACTIONS 
        IF DlgBox($Desktop,'USERS.DFC[ADDFORM]',$NullEvent,
           newUser) > 0 AND 
SQLInsert('USERS',newUser) > 0 THEN
           DlgListBoxInsert($Handle,'USERLIST',newUser); 
     END; 
     END (* Adicionar Usuário *);
     PROCEDURE EditUser IS; 
   ACTIONS 
       IF DlgFieldValue($Handle,'USERLIST',user) 
          > 0 AND 
          DlgBox($Desktop,'USERS.DFC[ADDFORM]',$NullEvent
{user},user) > 0 AND 
         SQLUpdate('USERS','USER_ID=''' 
          user.user_ID & '''',user) > 0 THEN 
          DlgListBoxUpdate($Handle,'USERLIST',user);
     END; 
     END (* Editar Usuário *);
     PROCEDURE DeleteUser IS; 
   ACTIONS 
IF DlgFieldValue($Handle,'USERLIST',user) > 0 AND 
          SQLDelete('USERS','USER_ID='''&user.user_ID&'''')
              > 0 THEN 
          DlgListBoxDelete($Handle,'USERLIST',user);
     END; 
     END (* Excluir Usuário *);
      ACTIONS 
     WHEN $Event IS $MsgCreate THEN 
       DlgSQLSelect($Handle,'USERLIST',user.$select);
     ELSWHEN $MsgSelect THEN 
       WHEN $FieldName IS 'ADD_BUTTON' THEN 
         AddUser; 
       ELSWHEN 'EDIT_BUTTON' THEN 
         EditUser; 
       ELSWHEN 'DELETE_BUTTON' THEN 
         DeleteUser; 
     END; 
     END;
   END (* Evento Usuário *);
   PROCEDURE WorkWithUsers IS; 
   VARIABLES
     UserWindow: WINDOW; 
     user: UserRecord; 
   ACTIONS
     user.$select = 'SELECT * FROM USERS'; 
     DlgCreate($Desktop,userWindow,
               'USERS.DFC [WORKWITHUSERS]',
               UserEvent{user}); 
   END (* Trabalhar com Usuários *); 

Explicação do exemplo

A função de WorkWithUsers é criar um formulário com os seguintes controles:

A rotina de tratamento de eventos UserEvent para o formulário processa estes eventos:

Table retém somente as informações especificadas por sua descrição de coluna. Isto poderia ser um subconjunto das colunas contidas na tabela de resultados de SQL. Quando você usa o comando DlgFieldValue para recuperar uma linha do controle Table, apenas os campos correspondentes às colunas daquele controle são retornados. Pode ser necessário executar um SQLSelectInto ou SQLSelect para concluir o restante do registro.

Como Criar Formulários

O TSD Script cria um novo formulário em um processo que envolve várias etapas:

Nota: Os dados na variável de ocorrência de registro substituem os valores de inicialização fornecidos no arquivo de formulário.

Formulários modais

Um formulário modal é aquele em que o programa aguarda o usuário aceitar ou cancelar o formulário antes de prosseguir. Quando uma caixa de diálogo modal é exibida, nenhuma outra janela pode ser selecionada.

Os formulários modais são criados com DlgBox. A instrução após DlgBox não é executada até que o usuário conclua o formulário criado. As informações especificadas pelo usuário são retornadas no quarto argumento para DlgBox. Esta é a variável de registro de saída.

Os formulários modais devem ser reservados principalmente para mensagens de erro importantes ou caixas de diálogo críticas onde o usuário não pode continuar sem responder uma pergunta. Um exemplo deste tipo de formulário pode ser uma mensagem que se refere à exclusão de arquivos.

Formulários não-modais

Um formulário não-modal é aquele no qual o aplicativo não aguarda pelo usuário antes de prosseguir. Isso significa que o usuário pode alternar para outras janelas enquanto o formulário é exibido.

Os formulários não-modais são criados com DlgCreate. Quando você faz uma chamada para DlgCreate, o processo de criação de um formulário é definido em movimento. No entanto, a execução da instrução seguinte ocorre simultaneamente.

O novo formulário tem sua própria interface com o usuário e seu próprio programa (sua rotina de tratamento de eventos).Ele continua existindo até que o usuário aceite ou cancele o formulário, ou até que outra parte do aplicativo envie a ele uma mensagem de fechamento ($MsgClose).

Nota: Em programação orientada à eventos, recomenda-se os formulários não-modais.

Formulários com separadores

O TSD Script oferece um tipo especial de formulário com "páginas" divisórias. Para mover de uma página a outra, o usuário escolhe os separadores.

Você cria os formulários com separadores no Criador de Interface do Developer's Toolkit especificando um ou mais formulários para combinação. Em tempo de execução, você pode usar estes formulários do mesmo modo como usa outros tipos de formulários. Eles podem ser criados com DlgBox ou DlgCreate. Para gerenciar seus eventos, você pode criar uma rotina de tratamento.

Quando você trabalhar com formulários com separadores, lembre-se do seguinte:


Tivoli Service Desk 6.0 Developer's Toolkit Script - Guia de Programação

Retornar ao Índice

Copyright