Tivoli Service Desk 6.0 Developer's Toolkit Script - Guia de Programaçã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:
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. |
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.
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.
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 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 |
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 |
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.
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.
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.
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.
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.
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 |
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.
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 é 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:
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:
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:
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:
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:
|
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 *);
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:
~ A mensagem $MsgSelect é gerada com o nome do botão de
comando, EDIT_BUTTON, passado em $FieldName.
~ A rotina de tratamento de eventos chama o procedimento EditUser para tratar deste evento.
EditUser primeiro usa a instrução DlgFieldValue para recuperar o valor da
linha selecionada.
~ Depois utiliza o formulário EDITFORM de USERS.DFC para criar um formulário no qual o usuário pode
fazer as alterações desejadas.
~ Quando o usuário aceita este formulário, a instrução SQLUpdate é usada para atualizar a linha na
tabela USERS e DlgListBoxUpdate
é usado para atualizar a linha correspondente no controle Table de USERLIST.
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.
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.
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.
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.
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