Docs / Referencia / Eventos A-Z

Referencia de Eventos A-Z

Esta pagina documenta todos os eventos disponiveis no HarbourBuilder. Eventos sao blocos de codigo atribuidos a propriedades de controle que sao invocados quando o evento correspondente do nivel do SO e acionado. Eventos formam o nucleo do modelo de programacao reativa do HarbourBuilder.

Como eventos funcionam

Cada evento e uma propriedade em um objeto de controle. Voce atribui um bloco de codigo Harbour ({ || ... }) a ele. Quando o usuario interage com o controle, o HarbourBuilder roteia o evento nativo do SO atraves do backend (Win32/Cocoa/GTK3) e avalia seu bloco de codigo.

Sintaxe de Atribuicao de Eventos

Eventos sao atribuidos usando o operador de atribuicao padrao Harbour com um bloco de codigo:

--- Evento simples: mostrar uma mensagem ---
oBtn:OnClick := { || MsgInfo( "Botao clicado!" ) }

--- Evento chamando uma funcao ---
oBtn:OnClick := { || ProcessClick( oBtn, oForm ) }

--- Evento com parametros (eventos de teclado) ---
oEdit:OnKeyDown := { | nKey, nFlags | HandleKey( nKey, nFlags ) }

--- Evento com coordenadas do mouse ---
oPaintBox:OnMouseMove := { | nX, nY | TrackMouse( nX, nY ) }

--- Bloco de codigo com multiplas instrucoes ---
oBtn:OnClick := { || ;
   LogAction( "botao clicado" ), ;
   MsgInfo( "Feito!" ), ;
   oForm:Close() ;
}

Eventos atribuidos pelo designer

No Designer de Formularios, selecione um controle, va a aba Eventos no Inspetor de Objetos, e de duplo clique em um evento. O IDE gera o bloco de codigo e salta para o editor de codigo.

Eventos do Mouse

Evento	Parametros	Controles Disponiveis	Descricao
`OnClick`	nenhum	Todos os controles interativos	Acionado quando o usuario clica no controle com o botao esquerdo do mouse. Este e o evento mais usado para botoes, itens de lista e nos de arvore.
`OnDblClick`	nenhum	Todos os controles interativos	Acionado no duplo clique. Para controles de lista/grade, isso geralmente aciona uma acao de "editar" ou "abrir". Para formularios, pode acionar comportamento padrao.
`OnMouseDown`	`nButton, nShiftState, nX, nY`	Todos os controles visuais	Acionado quando qualquer botao do mouse e pressionado. `nButton`: 1=esquerdo, 2=direito, 3=central. `nShiftState`: bitmask para Shift/Ctrl/Alt.
`OnMouseUp`	`nButton, nShiftState, nX, nY`	Todos os controles visuais	Acionado quando qualquer botao do mouse e solta. Util para conclusao de arrastar-e-soltar ou medicao de duracao de clique.
`OnMouseMove`	`nX, nY`	Todos os controles visuais	Acionado continuamente enquanto o mouse se move sobre o controle. Use com parcimonia; e acionado com muita frequencia. Bom para rastrear posicao do cursor ou efeitos de hover.
`OnMouseWheel`	`nDelta, nX, nY`	Todos os controles visuais	Acionado quando a roda do mouse e girada. `nDelta` e positivo para rolagem para frente/cima, negativo para tras/baixo. Tipicamente usado para zoom ou rolagem de conteudo.

Eventos do Teclado

Evento	Parametros	Controles Disponiveis	Descricao
`OnKeyDown`	`nKey, nFlags`	Todos os controles focaveis	Acionado quando uma tecla e pressionada. `nKey` e o codigo de tecla virtual (constantes VK_). `nFlags` contem contagem de repeticao e codigo de varredura.
`OnKeyUp`	`nKey, nFlags`	Todos os controles focaveis	Acionado quando uma tecla e solta. Util para detetar quanto tempo uma tecla foi mantida ou para deteccao de combinações de teclas.
`OnKeyPress`	`cKey`	Edit, Memo, MaskEdit, ComboBox	Acionado quando um caractere e digitado. `cKey` e o caractere real (nao codigo virtual). Permite modificar ou cancelar o caractere alterando o parametro.

Eventos de Foco e Selecao

Evento	Parametros	Controles Disponiveis	Descricao
`OnEnter`	nenhum	Todos os controles focaveis	Acionado quando o controle recebe foco de entrada (via Tab, clique ou programaticamente). Util para destacar o campo ativo ou mostrar ajuda contextual.
`OnExit`	nenhum	Todos os controles focaveis	Acionado quando o controle perde o foco. Use para validacao: verifique o valor do campo e previna perda de foco retornando `.F.` se invalido.
`OnChange`	nenhum	Edit, Memo, ComboBox, CheckBox, Radio, TrackBar, UpDown	Acionado quando o valor do controle e alterado. Para controles de edicao, acionado a cada tecla. Para combos, acionado quando a selecao muda.

Eventos do Ciclo de Vida do Formulario

Evento	Parametros	Controles Disponiveis	Descricao
`OnCreate`	nenhum	Form	Acionado quando o objeto formulario e criado pela primeira vez, antes de qualquer controle ser adicionado. Use para inicializacao precoce, carregamento de configuracao ou conexoes de dados.
`OnInit`	nenhum	Form	Acionado apos todos os controles serem criados e o formulario estar prestes a ser exibido. Este e o local ideal para configuracao final: popular listas, definir valores padrao, posicionamento.
`OnShow`	nenhum	Form	Acionado toda vez que o formulario se torna visivel. Acionado na exibicao inicial e novamente se o formulario foi ocultado e exibido novamente.
`OnHide`	nenhum	Form	Acionado quando o formulario e ocultado (via `Hide()` ou minimizado). Use para pausar timers ou parar tarefas em segundo plano.
`OnActivate`	nenhum	Form	Acionado quando o formulario recebe foco (se torna a janela ativa). Distinto de OnShow: um formulario pode ser exibido mas nao ativado se outra janela esta por cima.
`OnDeactivate`	nenhum	Form	Acionado quando o formulario perde o foco para outra janela na mesma aplicacao.
`OnActivateApp`	`lActive`	Form	Acionado quando toda a aplicacao ganha ou perde foco no nivel do SO. `lActive` e .T. quando o app esta em primeiro plano, .F. quando em segundo plano.
`OnCloseQuery`	`@lCanClose`	Form	Acionado antes do formulario fechar. Defina `lCanClose` como `.F.` para cancelar a operacao de fechamento. Use para prompts "Salvar alteracoes?".
`OnClose`	nenhum	Form	Acionado quando o formulario esta fechando (apos OnCloseQuery permitir). Use para limpeza: fechar conexoes de banco de dados, salvar estado, liberar recursos.
`OnDestroy`	nenhum	Form, todos os controles	Acionado quando o controle/formulario esta sendo destruido e a memoria esta prestes a ser liberada. Ultima chance para limpeza.

Eventos de Timer

Evento	Parametros	Controles Disponiveis	Descricao
`OnTimer`	nenhum	Timer	Acionado em intervalos regulares definidos pela propriedade `nInterval` do Timer (em milissegundos). Use para tarefas periodicas: atualizar um relogio, consultar um servidor, animar, salvar automaticamente.

Eventos de Pintura e Redimensionamento

Evento	Parametros	Controles Disponiveis	Descricao
`OnPaint`	nenhum	PaintBox, Form, Panel, Shape, todos os controles visuais	Acionado quando o controle precisa ser redesenhado. Use com PaintBox para desenho customizado GDI/Cairo. Acesse o contexto de dispositivo via funcoes de desenho especificas da plataforma.
`OnResize`	`nNewWidth, nNewHeight`	Form, Panel, ScrollBox	Acionado quando o container e redimensionado. Os parametros fornecem as novas dimensoes. Use para reposicionar controles filhos ou recalcular layout.

Tabela Resumo Completa de Eventos

Evento	Categoria	Controles Principais
`OnClick`	Mouse	Button, ListBox, TreeView, MenuItem, Image
`OnDblClick`	Mouse	ListBox, TreeView, StringGrid, Form
`OnMouseDown`	Mouse	Todos os controles visuais
`OnMouseUp`	Mouse	Todos os controles visuais
`OnMouseMove`	Mouse	Todos os controles visuais
`OnMouseWheel`	Mouse	Todos os controles visuais
`OnKeyDown`	Teclado	Todos os controles focaveis
`OnKeyUp`	Teclado	Todos os controles focaveis
`OnKeyPress`	Teclado	Edit, Memo, MaskEdit, ComboBox
`OnChange`	Valor	Edit, Memo, ComboBox, CheckBox, TrackBar
`OnEnter`	Foco	Todos os controles focaveis
`OnExit`	Foco	Todos os controles focaveis
`OnCreate`	Ciclo de Vida	Form
`OnInit`	Ciclo de Vida	Form
`OnShow`	Ciclo de Vida	Form
`OnHide`	Ciclo de Vida	Form
`OnActivate`	Ciclo de Vida	Form
`OnDeactivate`	Ciclo de Vida	Form
`OnActivateApp`	Ciclo de Vida	Form
`OnCloseQuery`	Ciclo de Vida	Form
`OnClose`	Ciclo de Vida	Form
`OnDestroy`	Ciclo de Vida	Todos os controles
`OnTimer`	Timer	Timer
`OnPaint`	Desenho	PaintBox, Shape, Form, Panel
`OnResize`	Layout	Form, Panel, ScrollBox

Ordem de disparo de eventos

Quando um usuario clica em um botao, a ordem dos eventos e: OnMouseDown → OnMouseUp → OnClick. Para entrada de teclado: OnKeyDown → OnKeyPress → OnKeyUp. Entender esta ordem ajuda voce a escolher o evento certo para seu caso de uso.

Nesta Página

Primeiros Passos Paleta de Componentes Recursos do IDE Tutoriais Referencia Plataformas Sintaxe de Atribuicao de Eventos Eventos do Mouse Eventos do Teclado Eventos de Foco e Selecao Eventos do Ciclo de Vida do Formulario Eventos de Timer Eventos de Pintura e Redimensionamento Tabela Resumo Completa de Eventos