Funções EditForm, NewForm, SubmitForm, ResetForm e ViewForm
Aplica-se a:
Aplicativos de tela
Ver, editar, ou criar um item, guardar o conteúdo e os controlos num controlo Edit form.
Descrição Geral
Estas funções alteram o estado do controlo Edit form. O controlo de formulário pode ser um destes modos:
| Modo | Descrição |
|---|---|
| FormMode.Editar | O formulário é preenchido com um registo existente e o utilizador pode modificar os valores dos campos. Depois de concluído, o utilizador pode guardar as alterações no registo. |
| FormMode.Novo | O formulário é preenchido com os valores predefinidos e o utilizador pode modificar os valores dos campos. Depois de concluído, o utilizador pode adicionar o registo à origem de dados. |
| FormMode.View | O formulário é preenchido com um registo existente, mas o utilizador pode modificar os valores dos campos. |
Descrição
Estas funções são, muitas vezes, invocadas a partir da fórmula OnSelect de um controlo Button ou Image para que o utilizador possa guardar as edições, abandonar edições ou criar um registo. Pode utilizar controlos e estas funções e controlos em conjunto para criar uma solução completa.
Estas funções não devolvem valores.
Pode utilizar estas funções apenas em fórmulas de comportamento.
SubmitForm
Utilize a função SubmitForm na propriedade OnSelect de um controlo Button para guardar quaisquer alterações num controlo Form na origem de dados.
Antes de submeter quaisquer alterações, esta função verifica a existência de problemas de validação com qualquer campo assinalado como necessário ou que tenha um ou mais restrições no respetivo valor. Este comportamento corresponde ao da função Validate.
SubmitForm também verifica a propriedade Valid do Form, que é uma agregação de todas as propriedades Valid dos controles cartão que o controle Form contém. Se ocorrer um problema, os dados não são submetidos e as propriedades Error e ErrorKind do controlo Form são definidos em conformidade.
Se a validação for aprovada, SubmitForm submete a alteração à origem de dados.
- Se for bem-sucedido, o comportamento OnSuccess do Formulário é executado e as propriedades Error e ErrorKind são eliminadas. Se o formulário estava no modo FormMode.New, é devolvido para o modo FormMode.Edit.
- Se não for bem-sucedido, o comportamento OnFailure do Formulário é executado e as propriedades Error e ErrorKind são definidas em conformidade. O modo do formulário permanece inalterado.
EditForm
A função EditForm altera o modo de controlo Form para FormMode.Edit. Neste modo, o conteúdo da propriedade Item do controlo Form é utilizado para preencher o formulário. Se a função SubmitForm é executada quando o formulário está neste modo, um registo é alterado e não é criado. FormMode.Edit é o padrão para o controle Form.
Nota
Quando o formulário está em modo de edição e Item é null, as propriedades do cartão de dados não são avaliadas e devolverão valores predefinidos.
NewForm
A função NewForm altera o modo de controlo Form para FormMode.New. Neste modo, o conteúdo da propriedade Item do controlo Form é ignorado e os valores predefinidos da propriedade DataSource do Formulário preenchem o formulário. Se a função SubmitForm é executada quando o formulário está neste modo, um registo é criado e não é alterado.
ResetForm
A função ResetForm repõe o conteúdo de um formulário para os valores iniciais, antes do utilizador efetuar quaisquer alterações. Se o formulário estiver no modo FormMode.New, o formulário é reposto para o modo FormMode.Edit. O comportamento OnReset do controlo de formulário também é executado. Pode também repor os controlos individuais com a função Reset, mas apenas a partir do formulário.
ViewForm
A função ViewForm altera o modo de controlo Form para FormMode.View. Neste modo, o conteúdo da propriedade Item do controlo Form é utilizado para preencher o formulário. As funções SubmitForm e ResetForm não têm qualquer efeito neste modo.
Propriedade DisplayMode
O modo atual pode ser lido através da propriedade Mode. O modo também determina o valor da propriedade DisplayMode, que pode ser utilizada por cartões de dados e controlos dentro do controlo de formulário. Muitas vezes, a propriedade DisplayMode do cartão de dados é definida para Parent.DisplayMode (com uma referência ao formulário) como a propriedade DisplayMode do controlo (com referência ao cartão de dados):
| Modo | DisplayMode | Descrição |
|---|---|---|
| FormMode.Editar | DisplayMode.Edit | Os cartões de dados e os controlos são editáveis e estão prontos para aceitar as alterações a um registo. |
| FormMode.Novo | DisplayMode.Edit | Os cartões de dados e controlos são editáveis e estão prontos para aceitar um novo registo. |
| FormMode.View | DisplayMode.View | Os cartões de dados e controlos não são editáveis e otimizados para visualização. |
Sintaxe
SubmitForm( FormName )
- FormName - Obrigatório. Controlo form para enviar à origem de dados.
EditForm( FormName )
- FormName - Obrigatório. Controlo form para mudar para o modo FormMode.Edit.
NewForm( FormName )
- FormName - Obrigatório. Controlo form para mudar para o modo FormMode.New.
ResetForm( FormName )
- FormName - Obrigatório. Controlo form para repor os valores iniciais. Também muda o formulário do modo FormMode.New para o modo FormMode.Edit.
ViewForm( FormName )
- FormName - Obrigatório. Controlo form para mudar para o modo FormMode.View.
Exemplos
Consulte Compreender os formulários de dados para obter exemplos de conclusão.
Adicione um controlo Button, defina a respetiva propriedade Text para mostrar Guardar e guardar a respetiva propriedade OnSelect para esta fórmula:
SubmitForm( EditForm )
Defina a propriedade OnFailure de um controlo Form para vazio e a respetiva propriedade OnSuccess para esta fórmula:
Voltar()
Atribua um controlo Label ErrorText e defina a respetiva propriedade Text para esta fórmula:
EditForm.Error
Quando o utilizador seleciona o botão Guardar, quaisquer alterações no controlo de Formulário são enviadas para a origem de dados subjacente.
- Se o envio for bem-sucedido, quaisquer alterações são guardadas ou, se o controlo Form estiver no modo Novo, é criado um registo. ErrorText está em branco e a tela anterior reaparece.
- Se o envio não for bem-sucedido, ErrorText mostra uma mensagem de erro amigável de utilizador e o ecrã atual permanece visível para que o utilizador possa corrigir o problema e tentar novamente.
Adicione um controlo Button, defina a respetiva propriedade Text para mostrar Cancelar e defina a respetiva propriedade OnSelect para esta fórmula:
ResetForm( EditForm ); Voltar()
Quando o utilizador seleciona o botão Cancelar, os valores no controlo Form são repostos para o que eram antes do utilizador começar a editá-los, o ecrã anterior é apresentado de novo e o controlo Form volta para o modo Editar, se estava no modo Novo.
Adicione um controlo Button, defina a respetiva propriedade Text para mostrar Novo e defina a respetiva propriedade OnSelect para esta fórmula:
NewForm( EditForm ); Navigate( EditScreen, Nenhum )
Quando o utilizador seleciona o botão Novo, o controlo de Formulário muda para o modo Novo, os valores predefinidos da origem de dados do controlo de Formulário preenchem esse controlo e é apresentado o ecrã que contém o controlo Form. Quando a função SubmitForm é executada, um registo é criado em vez de atualizado.