Controles de Dados

A aba Controles de Dados fornece 8 controles sensíveis a dados que se vinculam diretamente a campos de banco de dados e conjuntos de resultados. Esses controles exibem, navegam e editam dados de banco de dados automaticamente sem código de sincronização manual.

TBrowse CT_BROWSE = 79

Grade de dados de alto desempenho para navegar e editar dados tabulares. Suporta modos vinculado a banco de dados e virtual (blocos de código). O controle de exibição de dados mais poderoso do HarbourBuilder.

Propriedade	Tipo	Padrão	Descrição
oDataSource	Object	NIL	Componente de Acesso a Dados (TDBFTable, TSQLite, etc.)
aCols	Array	{}	Array de objetos TBrowseColumn
nRowCount	Numeric	0	Número de linhas visíveis (somente leitura)
nColCount	Numeric	0	Número de colunas (somente leitura)
nRowPos	Numeric	1	Posição atual da linha na área visível
nColPos	Numeric	1	Posição atual da coluna
lEditable	Logical	.F.	Permitir edição de célula no local
lVirtual	Logical	.F.	Usar modo virtual (dados fornecidos via blocos de código)
nVirtualRows	Numeric	0	Contagem total de linhas no modo virtual
lShowHeaders	Logical	.T.	Exibir linha de cabeçalho das colunas
lShowGrid	Logical	.T.	Exibir linhas da grade
lAlternateColors	Logical	.F.	Alternar cores de fundo das linhas
nClrRowOdd	Color	herdada	Cor de fundo de linhas ímpares
nClrRowEven	Color	herdada	Cor de fundo de linhas pares
nClrSelected	Color	sistema	Cor de destaque da linha selecionada

Propriedades de TBrowseColumn

Propriedade	Tipo	Padrão	Descrição
cHeading	String	""	Texto do cabeçalho da coluna
cField	String	""	Nome do campo de banco de dados para vincular
bBlock	Block	NIL	Bloco de código que retorna o valor da célula (modo virtual)
nWidth	Numeric	100	Largura da coluna em pixels
nAlign	Numeric	0	Alinhamento (0=esquerda, 1=centro, 2=direita)
cPicture	String	""	Cláusula de formato de exibição (picture)
lEditable	Logical	.T.	Permitir edição nesta coluna

Eventos do TBrowse

Evento	Categoria	Descrição
OnClick	Ação	Usuário clicou em uma célula. Params: nRow, nCol
OnDblClick	Ação	Usuário deu clique duplo em uma célula. Params: nRow, nCol
OnRowChange	Navegação	Linha atual alterada. Params: nOldRow, nNewRow
OnColChange	Navegação	Coluna atual alterada. Params: nOldCol, nNewCol
OnHeaderClick	Ação	Cabeçalho da coluna clicado (para ordenação). Params: nCol
OnBeforeEdit	Edição	Antes do início da edição da célula. Retorne .F. para cancelar. Params: nRow, nCol
OnAfterEdit	Edição	Após confirmação da edição da célula. Params: nRow, nCol, xOldValue, xNewValue
OnKeyDown	Teclado	Tecla pressionada enquanto o browse tem foco. Params: nKey
OnPaint	Exibição	Pintura personalizada da célula. Params: nRow, nCol, oCanvas
OnVirtualData	Dados	Solicitação de dados para uma linha virtual. Params: nRow, nCol. Deve retornar o valor da célula

Plataforma	Widget Nativo
Windows	ListView owner-drawn personalizado (WC_LISTVIEW)
macOS	NSScrollView + NSTableView
Linux	GtkScrolledWindow + GtkTreeView

TDBGrid CT_DBGRID = 80

Grade de dados simplificada que gera colunas automaticamente a partir dos campos da fonte de dados. Mais fácil de usar que TBrowse quando personalização completa não é necessária.

Propriedade	Tipo	Padrão	Descrição
oDataSource	Object	NIL	Componente de Acesso a Dados para vincular
lAutoColumns	Logical	.T.	Criar colunas automaticamente a partir dos campos
lEditable	Logical	.F.	Permitir edição no local
lSortable	Logical	.T.	Permitir ordenação clicando nos cabeçalhos

Evento	Categoria	Descrição
OnClick	Ação	Célula clicada
OnDblClick	Ação	Célula com clique duplo
OnRowChange	Navegação	Linha atual alterada
OnAfterEdit	Edição	Edição da célula confirmada

TDBNavigator CT_DBNAVIGATOR = 81

Barra de navegação com botões para primeiro, anterior, próximo, último, inserir, excluir, editar, salvar e cancelar operações em uma fonte de dados.

Propriedade	Tipo	Padrão	Descrição
oDataSource	Object	NIL	Componente de Acesso a Dados para navegar
lShowInsert	Logical	.T.	Exibir botão Inserir
lShowDelete	Logical	.T.	Exibir botão Excluir
lShowEdit	Logical	.T.	Exibir botão Editar
lConfirmDelete	Logical	.T.	Solicitar confirmação antes de excluir um registro

Evento	Categoria	Descrição
OnBeforeAction	Ação	Antes de uma ação do navegador. Retorne .F. para cancelar. Params: nAction
OnAfterAction	Ação	Após conclusão de uma ação do navegador. Params: nAction

TDBText CT_DBTEXT = 82

Rótulo sensível a dados. Exibe automaticamente o valor de um campo vinculado de banco de dados como texto somente leitura.

Propriedade	Tipo	Padrão	Descrição
oDataSource	Object	NIL	Componente de Acesso a Dados
cField	String	""	Nome do campo a exibir
cPicture	String	""	Cláusula de formato de exibição (picture)

TDBEdit CT_DBEDIT = 83

Campo de entrada de texto sensível a dados. Vincula um controle TEdit a um campo de banco de dados para visualização e edição.

Propriedade	Tipo	Padrão	Descrição
oDataSource	Object	NIL	Componente de Acesso a Dados
cField	String	""	Nome do campo para vincular
cPicture	String	""	Cláusula de formato de entrada/exibição (picture)
lReadOnly	Logical	.F.	Impedir edição

Evento	Categoria	Descrição
OnChange	Ação	Valor do campo alterado pelo usuário
OnValidate	Validação	Validar antes de salvar. Retorne .F. para rejeitar. Params: xValue

TDBComboBox CT_DBCOMBOBOX = 84

Caixa de combinação sensível a dados. Exibe uma lista suspensa vinculada a um campo de banco de dados. Útil para campos de pesquisa.

Propriedade	Tipo	Padrão	Descrição
oDataSource	Object	NIL	Componente de Acesso a Dados
cField	String	""	Nome do campo para vincular
aItems	Array	{}	Lista de itens selecionáveis
oLookupSource	Object	NIL	Fonte de dados de pesquisa opcional para itens
cLookupField	String	""	Campo da fonte de pesquisa para exibir
cLookupKey	String	""	Campo chave da fonte de pesquisa

Evento	Categoria	Descrição
OnChange	Ação	Seleção alterada

TDBCheckBox CT_DBCHECKBOX = 85

Caixa de seleção sensível a dados. Vincula um campo lógico (booleano) de banco de dados a um controle de caixa de seleção.

Propriedade	Tipo	Padrão	Descrição
oDataSource	Object	NIL	Componente de Acesso a Dados
cField	String	""	Nome do campo lógico para vincular
cText	String	""	Texto do rótulo ao lado da caixa de seleção
xValueOn	Any	.T.	Valor representando o estado selecionado
xValueOff	Any	.F.	Valor representando o estado não selecionado

Evento	Categoria	Descrição
OnChange	Ação	Estado da caixa de seleção alterado

TDBImage CT_DBIMAGE = 86

Exibição de imagem sensível a dados. Mostra uma imagem armazenada em um campo BLOB de banco de dados ou referenciada por um caminho de arquivo.

Propriedade	Tipo	Padrão	Descrição
oDataSource	Object	NIL	Componente de Acesso a Dados
cField	String	""	Nome do campo BLOB ou caminho de arquivo
lStretch	Logical	.F.	Esticar a imagem para preencher o controle
lProportional	Logical	.T.	Manter a proporção ao esticar
lIsPath	Logical	.F.	Campo contém um caminho de arquivo (não dados binários)

Exemplo de Código: TBrowse com Banco de Dados

// Um formulário de navegação de dados com TBrowse, navegador e controles sensíveis a dados

FUNCTION Main()

   LOCAL oForm, oDB, oBrw, oNav

   // Criar formulário
   oForm := TForm():New()
   oForm:cTitle := "Navegador de Clientes"
   oForm:nWidth := 800
   oForm:nHeight := 500

   // Conectar ao banco de dados
   oDB := TSQLite():New()
   oDB:cFile := "customers.db"
   oDB:lAutoConnect := .T.

   // Criar o controle de navegação
   oBrw := TBrowse():New( oForm )
   oBrw:nLeft   := 10
   oBrw:nTop    := 10
   oBrw:nWidth  := 780
   oBrw:nHeight := 350
   oBrw:oDataSource := oDB
   oBrw:lAlternateColors := .T.

   // Definir colunas
   oBrw:AddColumn( "Id",    "id",    60,  2 )  // alinhado à direita
   oBrw:AddColumn( "Name",  "name",  200, 0 )  // alinhado à esquerda
   oBrw:AddColumn( "Email", "email", 250, 0 )
   oBrw:AddColumn( "City",  "city",  150, 0 )

   // Eventos
   oBrw:OnDblClick    := { |r,c| EditRecord( oDB, r ) }
   oBrw:OnHeaderClick := { |c| SortByColumn( oDB, oBrw, c ) }
   oBrw:OnRowChange   := { |o,n| UpdateStatus( n ) }

   // Adicionar barra de navegação
   oNav := TDBNavigator():New( oForm )
   oNav:nLeft := 10
   oNav:nTop  := 370
   oNav:oDataSource := oDB
   oNav:lConfirmDelete := .T.

   // Carregar dados e ativar
   oDB:Query( "SELECT * FROM customers ORDER BY name" )
   oForm:Activate()

RETURN NIL