Header Web
Logo_PHC_Software
Manuais
Eventos
Este tipo de propriedades só disponíveis na gama Enterprise, são expressões em Xbase, que podem ser ou não programadas, servem para o utilizador poder configurar comportamentos dos objetos quando determinada ação corre no programa, estas ações são o que chamamos de eventos.
Assim, quando um determinado evento é disparado pela aplicação o objeto em causa recebe a notificação desse evento e atua de acordo com o que foi codificado pelo utilizador na respetiva propriedade.

Em cada um dos tipos de eventos disponíveis, caso a expressão Xbase seja um programa (opção é um programa) o utilizador pode usar no seu código um objeto que tem duas ou mais propriedades, consoante o tipo de evento que se está a programar.
Este objeto chama-se ObjRecebido, está sempre disponível nas expressões Xbase que sejam programas e disponibiliza ao utilizador várias funcionalidades de modo a ser possível configurar não só o comportamento do objeto em causa como também afetar algumas propriedades dos objetos que o rodeiam, sejam eles objetos do utilizador ou os próprios objetos do ecrã.

As duas propriedades que o objeto tem sempre disponíveis são:
Janela e Objeto

A propriedade Janela é um apontador para o ecrã onde se está a criar ou modificar determinada página. Esta propriedade é do tipo objeto a através dela acede-se a todas as propriedades que o objeto disponibiliza, podendo-se assim consultar ou modificar essas propriedades.
Por exemplo, o seguinte código altera o título do ecrã:
ObjRecebido.Janela.Caption="Exemplo de Demonstração"
As alterações destas propriedades só são efetuadas enquanto o ecrã se mantiver aberto, porque como não são gravadas na base de dados, quando o utilizador fechar o ecrã e voltar a abrir o mesmo o título volta ao normal, a não ser que este código seja introduzido num evento que seja disparado sempre que o ecrã é chamado, como por exemplo o Evento Init.
A propriedade Caption ou ainda a BackColor são exemplos das propriedades do objeto Janela, o utilizador pode alterar qualquer outra propriedade, para obter uma lista das propriedades disponíveis pode utilizar a opção Objetos deste ecrã.

A propriedade Objeto é um apontador para o próprio objeto no qual é programado o evento. Uma das propriedades disponibilizadas por este objeto é Value, nos objetos que suportam esta propriedade ela indica o valor atual do objeto.
Outra das propriedades é Parent, esta propriedade é uma referência para o objeto pai do objeto que se está a programar.
Por exemplo:
Existe um objeto numa página de utilizador, esta página está num ecrã, logo a seguinte instrução:
ObjRecebido.Objecto.Parent.Parent.Caption="Exemplo de Demonstração"
Faz exatamente o mesmo que a instrução apresentada anteriormente ObjRecebido.Janela.Caption="Exemplo de Demonstração"
enquanto que ObjRecebido.Objecto.Parent.Caption="Exemplo de Demonstração" muda o título da página do utilizador ao invés do título do ecrã.
Se na mesma página de utilizador existir um objeto do tipo Texto com o nome Obj3, a seguinte linha de código muda o texto mostrado por esse objeto:
ObjRecebido.Objecto.Parent.Obj3.Caption="O Texto deste Objecto foi alterado".
A única situação onde a propriedade Objeto não aponta para o próprio objeto é quando esse objeto é um pouco mais complexo, ou seja, não é um objeto mas sim um conjunto de objetos. exemplo disso é o objeto Campo de Ligação em que esta propriedade aponta pata o objeto "Pai" que contém os outros objetos que constituem o campo de ligação. Assim neste caso:
. ObjRecebido.Objecto.Lista1 (para se referenciar o botão de lista)
. ObjRecebido.Objecto.Nossocampo1 (para se referenciar o objeto que aceita o texto introduzido pelo utilizador)
. ObjRecebido.Objecto.Procura (para se referenciar o botão de procura)

A propriedade Objecto disponibiliza outra propriedade muito útil, que se chama MeusDados, como esta propriedade é um objeto, disponibiliza várias propriedades que são:
TotalParametros
AddParametro
GuardaParametro
ExisteParametro
GetNomeParametro
GetIndexParametro
Este objecto (MeusDados) como o seu nome indica, serve para guardar os dados que sejam precisos para codificar determinados eventos, por exemplo no Evento Init poder guardar informação e depois no evento Refrescar ir buscar essa mesma informação.
Em suma, este objeto serve como repositório de dados do utilizador, sendo os seus dados guardados com pares de Chave - Dados, ou seja para cada valor guardado existe uma chave associada a ele de modo a permitir posteriormente retornar esse valor do conjunto de valores que o objeto poderá conter.

O significado de cada uma das propriedades deste objeto é o seguinte:
TotalParametros
Esta propriedade é só de leitura e retorna o número de chaves que o utilizador guardou no objeto.

AddParametro
É o método para adicionar uma determinada chave e o seu valor.
Por exemplo:
ObjRecebido.Objecto.MeusDados.AddParametro("CorFundoAntiga",ObjRecebido.Objecto.BackColor)
Este método limita-se a tentar criar uma nova chave com o valor especificado. Se por acaso já existir uma chave com o mesmo nome o método não adiciona nada, nem sequer modifica o valor da chave que já existia.
Retorna sempre um valor lógico:
.T. caso consiga adicionar a chave e .F. caso não adicione a chave por já existir uma com o mesmo nome ou por ter ocorrido um erro interno.

GuardaParametro
Este método permite adicionar/modificar uma determinada chave e o seu valor.
Por exemplo:
ObjRecebido.Objecto.MeusDados.GuardaParametro("CorFundoAntiga",ObjRecebido.Objecto.BackColor)
Este método tem um comportamento idêntico ao anterior (AddParametro), mas neste caso verifica primeiro se a chave já existe. Se já existir modifica o seu valor para o novo que se está a especificar, se não existir cria uma nova chave a atribui-lhe o respetivo valor.

ExisteParametro
Este método retorna um valor lógico que indica se determinada chave existe no objeto.
Por exemplo:
ObjRecebido.Objecto.MeusDados.ExisteParametro("CorFundoAntiga")
Neste caso o resultado seria .T., porque existe.
ObjRecebido.Objecto.MeusDados.ExisteParametro("MaisUmaCor")
Assumindo que ainda só se teria adicionado uma chave com o nome "CorFundoAntiga", a instrução anterior retorna .F. , porque não existe.

GetNomeParametro
Este método retorna o nome de determinada chave mediante a sua posição na coleção de chaves guardadas no objeto.
Por exemplo:
ObjRecebido.Objecto.MeusDados.GetNomeParametro(1)
O valor retornado é sempre do tipo carater, neste caso o valor retornado seria "CorFundoAntiga".

GetIndexParametro
Este método é o inverso do método anterior (GetNomeParametro), pois neste o que é enviado é o nome da chave e é retornado a posição dessa chave na coleção de chaves guardadas do objeto.
Por exemplo:
ObjRecebido.Objecto.MeusDados.GetIndexParametro("CorFundoAntiga")
Neste caso o valor retornado é do tipo numérico e seria 1.
Para utilizar o valor guardado neste objeto, basta fazer por exemplo para obter o valor guardado sob a chave "CorFundoAntiga":
ObjRecebido.Objecto.MeusDados.CorFundoAntiga


Assim:
ObjRecebido.Objecto.MeusDados.GuardaParametro("CorFundoAntiga",ObjRecebido.Objecto.BackColor)
Esta instrução guarda o valor
ObjRecebido.Objecto.BackColor=rgb(0,255,255)
Esta instrução atribui uma nova cor
ObjRecebido.Objecto.BackColor=ObjRecebido.Objecto.MeusDados.CorFundoAntiga
Esta instrução repõe a cor inicial

Em alguns eventos o número de propriedades do objeto ObjRecebido pode variar consoante as necessidades do evento, mas as duas mencionadas anteriormente tem sempre.

Os diversos eventos disponíveis são:

Evento Ativar
Evento Antes mudar Linha/Coluna
Evento ao Entrar
Evento ao Sair
Evento Após Atualizar
Evento Após não Atualizado
Evento Clique
Evento Clique Direito
Evento Depois mudar Linha/Coluna
Evento Desativar
Evento Duplo Clique
Evento Init
Evento MouseEnter
Evento MouseLeave
Evento MouseMove
Evento MouseWheel
Evento Refrescar
Evento Tecla Pressionada


Cada evento poderá ter um retorno especificado com o comando "Return...", o valor retornado será depois usado pela rotina interna da aplicação que disparou o evento para determinar o restante funcionamento do evento. Ou seja, por exemplo no Evento Tecla Pressionada, caso se utilize "Return .F." apesar da tecla ter sido pressionada e processada, o objeto por exemplo um campo de ficheiro não recebe esse valor, é como se o teclado estivesse desligado.
Nos objeto do tipo Campos de Ficheiro, caso a variável do objeto seja do tipo Data, o utilizador pode fazer clique direito do rato sobre o campo para aparecer um calendário, no caso do Evento Clique Direito retornar .F. o calendário já não é mostrado.

Resumindo, no caso do valor retornado pelos eventos ser .F. e o objeto em questão ter código de raiz para ser executado quando se executa determinada ação, esse código não é executado, podendo-se assim alterar o comportamento preestabelecido de determinados objetos, isto porque por defeito o valor de retorno está configurado para retornar sempre .T. ou pelo menos retornar algo que signifique que o código de raiz do objeto para determinado evento execute.


Dicas:
Quando verificar que determinado evento não está a executar o que era suposto, deve ir à Análise Interna, pois é nesse local que ficam gravados os erros que ocorrem na execução dos eventos.
Ao observar o texto do erro, caso o número da linha seja 0 (zero) é porque a expressão Xbase que foi avaliada nesse evento não é um programa mas sim uma expressão. Nestes casos quando são expressões a avaliar não é registado o número da linha, até porque se for apenas uma expressão a executar essa só pode ter uma linha.
Não esquecer que caso seja uma expressão não se pode utilizar a palavra "Return", isto porque os valores são retornados automaticamente pelas expressões .