DIALOG

DIALOG ( {tabela ;} formulario {; dataForm}{; *} )

Parâmetro	Tipo		Descrição
tabela	Table	→	Tabela a qual pertence o formulário ou se omitida: tabela por padrão ou uso do formulário de projeto
formulario	Text, Object	→	Nome de tabela ou formulário de projeto a mostrar como diálogo
dataForm	Object	→	Dados a associar ao formulário
*	Operador	→	Utilizar o mesmo processo

Descrição

O comandoDIALOG apresenta o formulário formulario ao usuário. Este comando se designa para trabalhar com interfaces de usuário avançadas e personalizadas baseadas em formulários. Pode utilizá-lo para mostrar informação do banco de dados ou de outras localizações, ou para oferecer funcionalidades de entrada de dados. Diferente de ADD RECORD o u MODIFY RECORD, DIALOG lhe dá controle total sobre o formulário, seu conteúdo e os botões de navegação e validação.

Este comando geralmente se chama junto com Open form window para mostrar formulários sofisticados, como é mostrado no exemplo abaixo:

Utilize DIALOG ao invés de ALERT, CONFIRM ou Request quando a informação que deve ser apresentada ou reunida é mais complexa do que esses comandos podem manejar.

Nota: em bancos de dados convertidos, é possível proibir a entrada de dados em campos ou caixas de diálogo (e limitar a entrada de dados a variáveis unicamente) utilizando uma opção nas Preferências de 4D (página Compatibilidade). Esta restrição corresponde ao funcionamento de versões anteriores de 4D.

No parâmetro formulario, pode passar

o nome de um formulário;
a rota (em sintaxe POSIX) para um arquivo json válido contendo uma descrição doe formulário a usar. Veja Form file path;
um objeto que contenha a descrição do formulário.

Opcionalmente, pode passar parâmetros ao formulário mediante o objeto formData. Toda propriedade de objeto formData estará disponível desde o contexto de formulário mediante o comando Form. Por exemplo, se passar um objeto que contenha {"version","12"} em formData, poderá obter o valor da propriedade "Version" no formulário chamando:

 $v:=Form.version //"12"

Utilizando uma variável local para formData, esta funcionalidade lhe permite passar parâmetros de maneira segura a seus formulários, qualquer que seja o contexto da chamada. Em particular, se o mesmo formulário se chama desde diferentes lugares no mesmo processo, sempre poderá acessar a seus valores específicos simplesmente chamando a Form.myProperty. Além disso, dado que os objetos são passados por referência, se o usuário modificar um valor de propriedade no formulário, este se guardará automaticamente no mesmo objeto.
Ao combinar o objeto formData e o comando Form, pode enviar parâmetros ao formulário ou ler os parâmetros em qualquer momento com código limpo e seguro.

Nota: se não passar nenhum parâmetro formData ou se passar um objeto indefinido, DIALOG cria automaticamente um novo objeto vazio vinculado ao form e disponível através de comando Form.

O diálogo é aceito se o usuário clicar no botão Aceitar ou pressionar a tecla Enter (teclado numérico) ou se é executado o comando ACCEPT.
Lembre que a validação não faz com que os dados modificados sejam guardados. Se o diálogo inclui campos, deve chamar explicitamente ao comando SAVE RECORD para guardar os dados que tenham sido modificados.

O diálogo é cancelado se o usuário clicar no botão Cancelar ou pressionar a tecla de anulação Esc ou se são executa o comando CANCEL.

Se passar o parâmetro opcional *, o formulário é carregado e mostra na última janela do processo atual e o comando termina sua execução enquanto deixa o formulário ativo em tela.

Este formulário logo reage "normalmente" as ações do usuário e é fechado quando o código 4D relacionado com o formulário (método de objeto ou método de formulário) chama ao comando CANCEL ou ACCEPT Se o processo atual termina, os formulários criados desta forma são fechados automaticamente da mesma forma que se tivesse chamado o comando CANCEL. Este modo de abertura é particularmente útil para mostrar uma palheta flutuante com um documento, sem necessidade de outro processo.

Notas:

• Pode combinar o uso da sintaxe DIALOG(form;*) com o comando CALL FORM para estabelecer a comunicação entre os formulários
• deve criar uma janela antes de chamar a instrução DIALOG("form";*); se não for possível utilizar a janela de diálogo atual no processo nem a janela criada por padrão para cada processo. Do contrário, se gera o erro -9909.
• Quando for utilizado o parâmetro *, a janela é fechada automaticamente depois de uma ação padrão ou uma chamada ao comando CANCEL ou ACCEPT. Não tem que gerenciar o fechamento da própria janela.

Exemplo 1

O exemplo a seguir pode ser usado para criar uma palheta de ferramentas

  //Mostra a palheta de ferramentas
 $palette_window:=Open form window("tools";Palette form window)
 DIALOG("tools";*) //Devolva o controle imediatamente
  //Mostra janela do documento principal
 $document_window:=Open form window("doc";Standard form window)
 DIALOG("doc")

Exemplo 2

Em um formulário exibindo o registro de uma pessoa, um botão "Check children" abre um diálogo para verificar/modificar os nomes e idades dos filhos:

Nota: O campo objeto "Children" é representado apenas para mostrar sua estrutura para esse exemplo.

No formulário de verificação, se tiver atribuido algumas propriedades de objeto a variáveis Form:

Abaixo o código para o botão "Check children":

 var $win;$n;$i : Integer
 var $save : Boolean
 ARRAY OBJECT($children;0)
 OB GET ARRAY([Person]Children;"children";$children) //obtém a coleção children
 $save:=False //initializa a variável save
 
 $n:=Size of array($children)
 If($n>0)
    $win:=Open form window("Edit_Children";Movable form dialog box)
    SET WINDOW TITLE("Check children for "+[Person]Name)
    For($i;1;$n) //para cada child
       DIALOG("Edit_Children";$children{$i}) //exibe diálogo preenchido com valores
       If(OK=1) //o usuário clica OK
          $save:=True
       End if
    End for
    If($save=True)
       [Person]Children:=[Person]Children //força a atualização do campo objeto
    End if
    CLOSE WINDOW($win)
 Else
    ALERT("No child to check.")
 End if

Nota: Esse exemplo exige que a notação de objeto esteja ativada no banco de dados (ver Página Compatibilidade).

O formulário exibe informação para cada campo:

Se os valores forem editados e o botão OK button for clicaod, o campo é atualizado (o registro pai deve ser salvo depois).

Exemplo 3

O exemplo abaixo usa a rota a um formulário json para exibir os registros em uma lista de empregados:

 Open form window("/RESOURCES/OutputPersonnel.json";Plain form window)
 ALL RECORDS([Personnel])
 DIALOG("/RESOURCES/OutputPersonnel.json";*)

o que retorna:

Exemplo 4

O exemplo abaixo utiliza um aquivo .json como um objeto e modifica algumas propriedades:

 var $form : Object
 $form:=JSON Parse(Document to text(Get 4D folder(Current resources folder)+"OutputPersonnel.json"))
 $form.windowTitle:="The Avengers"
 $form.pages[1].objects.logo.picture:="/RESOURCES/Images/Avengers.png"
 $form.pages[1].objects.myListBox.borderStyle:="double"
 Open form window($form;Plain form window)
 DIALOG($form;*)

O formulário modificado é devolvido com o título, o logotipo e a borda modificados:

Variáveis e conjuntos do sistema

Depois de chamar a DIALOG, se o diálogo é aceito, a variável sistema OK toma o valor 1; se for cancelado toma o valor 0.

Ver também

ACCEPT
ADD RECORD
CALL FORM
CANCEL
Form
Open window

Propriedades

Número do comando	40
Thread-seguro	✗
Modificar variáveis	OK, error