Funções EditForm NewForm, SubmitForm, ResetForm e ViewForm
Aplica-se a:
aplicativos Canvas
Exiba, edite ou crie um item, salve o conteúdo e redefina os controles em um controle Edit form.
Visão Geral
Essas funções alteram o estado do controle Edit form. O controle de formulário pode estar em um destes modos:
| Modo | Descrição |
|---|---|
| Modo de formulário.Editar | O formulário é preenchido com um registro existente e o usuário pode modificar os valores dos campos. Uma vez concluído, o usuário pode salvar as alterações no registro. |
| ModoFormulário.Novo | O formulário é populado com valores padrão e o usuário pode modificar os valores dos campos. Uma vez concluído, o usuário pode adicionar o registro à fonte de dados. |
| Modo de formulário.Exibir | O formulário é preenchido com um registro existente, mas o usuário não pode modificar os valores dos campos. |
Descrição
Geralmente, essas funções são invocadas com a fórmula OnSelect de um controle Button ou Image para que os usuários possam salvar edições, abandonar edições ou criar um registro. Você pode usar controles e essas funções juntas para criar uma solução completa.
Essas funções não retornam valores.
Você pode usar essas funções somente nas fórmulas de comportamento.
SubmitForm
Use a função SubmitForm na propriedade OnSelect de um controle Button para salvar alterações feitas em um controle Form para a fonte de dados.
Antes de enviar qualquer alteração, essa função verifica problemas de validação em todos os campos marcados como obrigatórios ou que têm uma ou mais restrições em seus valores. Esse comportamento corresponde ao da função Validate.
SubmitForm também verifica a propriedade Valid do Formulário, que é uma agregação de todas as propriedades Valid dos controles cartão que o controle Formulário contém. Se um problema ocorrer, os dados não serão enviados e as propriedades Error e ErrorKind do controle Form serão definidas de acordo.
Se a validação for aprovada, a função SubmitForm enviará a alteração para a fonte de dados.
- Se tiver êxito, o comportamento OnSuccess do formulário será executado e as propriedades Error e ErrorKind serão apagadas. Se o formulário estiver no modo FormMode.New, ele retornará ao modo FormMode.Edit.
- Se não tiver êxito, o comportamento OnFailure do formulário será executado e as propriedades Error e ErrorKind serão definidas de acordo. O modo do formulário não é alterado.
EditForm
A função EditForm altera o modo do controle Form para FormMode.Edit. Nesse modo, o conteúdo da propriedade Item do controle Form é usado para preencher o formulário. Se a função SubmitForm for executada quando o formulário estiver nesse modo, um registro será alterado, não criado. FormMode.Edit é o padrão para o controle Form.
Observação
Quando o formulário está em modo de edição e o Item é nulo, as propriedades do cartão de dados não são avaliadas e retornarão os valores padrão.
NewForm
A função NewForm altera o modo do controle Form para FormMode.New. Nesse modo, o conteúdo da propriedade Item do controle Form é ignorado e os valores padrão da propriedade DataSource de Formulário preenchem o formulário. Se a função SubmitForm for executada quando o formulário estiver nesse modo, um registro será criado, não alterado.
ResetForm
A função ResetForm redefine o conteúdo de um formulário para valores iniciais, presentes antes de o usuário fazer alterações. Se o formulário estiver no modo FormMode.New, ele será redefinido no modo FormMode.Edit. O comportamento OnReset do controle de formulário também é executado. Você também pode redefinir controles individuais com a função Reset, mas apenas dentro do formulário.
ViewForm
A função ViewForm altera o modo do controle Form para FormMode.View. Nesse modo, o conteúdo da propriedade Item do controle Form é usado para preencher o formulário. As funções SubmitForm e ResetForm não têm efeito nesse modo.
Propriedade DisplayMode
O modo atual pode ser lido por meio da propriedade Mode. O modo também determina o valor da propriedade DisplayMode, que pode ser usada por cartões de dados e controles dentro do controle de formulário. Geralmente, a propriedade DisplayMode do cartão de dados será definida como Parent.DisplayMode (referência ao formulário), assim como ocorrerá com a propriedade DisplayMode do controle (referência ao cartão de dados):
| Modo | Modo de exibição | Descrição |
|---|---|---|
| Modo de formulário.Editar | Modo de Exibição.Editar | Cartões de dados e controles são editáveis, prontos para aceitar alterações em um registro. |
| ModoFormulário.Novo | Modo de Exibição.Editar | Cartões de dados e controles são editáveis, prontos para aceitar um novo registro. |
| Modo de formulário.Exibir | Modo de exibição.Exibir | Cartões de dados e controles não são editáveis e otimizados para exibição. |
Sintaxe
EnviarFormulário( FormName )
- FormName - Obrigatório. O controle Form a ser enviado para a fonte de dados.
EditarFormulário( NomeDoFormulário )
- FormName - Obrigatório. O controle Form para alternar para o modo FormMode.Edit.
NovoFormulário( NomeDoFormulário )
- FormName - Obrigatório. O controle Form para alternar para o modo FormMode.New.
ResetForm( NomeDoFormulário )
- FormName - Obrigatório. O controle Form para redefinir com os valores iniciais. Também alterna o formulário do modo FormMode.New para o modo FormMode.Edit.
ViewForm( NomeDoFormulário )
- FormName - Obrigatório. O controle Form para alternar para o modo FormMode.View.
Exemplos
Consulte Entender formulários de dados para obter exemplos completos.
Adicione um controle Button, defina a propriedade Text para mostrar Salvar e defina a propriedade OnSelect com esta fórmula:
EnviarFormulário(EditarFormulário)
Defina a propriedade OnFailure de um controle Form para ficar em branco e a propriedade OnSuccess com esta fórmula:
Voltar()
Nomeie um controle Label como ErrorText e defina a propriedade Text com esta fórmula:
EditarFormulário.Erro
Quando o usuário selecionar o botão Salvar, qualquer alteração no controle Form será enviada à fonte de dados subjacente.
- Se o envio for bem-sucedido, todas as alterações serão salvas ou, se o controle Form estiver no modo New, um registro será criado. ErrorText está em branco e a tela anterior reaparece.
- Se o envio falhar, ErrorText mostrará uma mensagem de erro amigável e a tela atual permanecerá visível para que o usuário possa corrigir o problema e tentar novamente.
Adicione um controle Button, defina a propriedade Text para mostrar Cancelar e defina a propriedade OnSelect com esta fórmula:
ResetForm(EditForm); Voltar()
Quando o usuário selecionar o botão Cancelar, os valores no controle Form serão redefinidos com os valores definidos antes de o usuário iniciar a edição, a tela anterior será reexibida e o controle Form voltará ao modo Edit, caso esteja no modo New.
Adicione um controle Button, defina a propriedade Text para mostrar Novo e defina a propriedade OnSelect com esta fórmula:
NewForm(EditForm); Navegar(EditScreen, Nenhum)
Quando o usuário selecionar o botão New, o controle Form alternará para o modo New, os valores padrão da fonte de dados do controle Form preencherão esse controle e a tela que apresenta o controle Form será exibida. Quando a função SubmitForm é executada, um registro é criado, em vez de atualizado.