nRow, nColNuméricoObrigatório
Linha e coluna em que o browse será posicionado. Com PIXEL, as coordenadas partem do canto superior esquerdo do componente pai.
COMANDOPublicado
@ ... BROWSE
@ <nRow>, <nCol> [COLUMN] BROWSE <oBrw> [FIELDS <campos>] [ALIAS <cAlias>] [SIZE <nWidth>, <nHeight>] [OF <oDlg>] [PIXEL]Cria um componente TCBrowse para navegar e apresentar dados de tabelas ou arrays.
Visão geral
O comando @ ... BROWSE cria uma grade de navegação visual e armazena o objeto resultante em uma variável AdvPL. Na compilação, a sintaxe é convertida para o construtor New() da classe TCBrowse. O componente pode receber campos de uma tabela e seu alias diretamente ou ser criado vazio, associado a um array com SetArray() e preenchido com colunas adicionadas posteriormente.
Sintaxe
@ <nRow>, <nCol> [COLUMN] BROWSE <oBrw> [FIELDS <campos>] [ALIAS <cAlias>] [SIZE <nWidth>, <nHeight>] [OF <oDlg>] [PIXEL]Parâmetros
oBrwObjetoObrigatório
Variável que receberá o objeto TCBrowse criado.
FIELDS camposCaractereOpcional
Campos da tabela que formarão as colunas. A palavra FIELDS é opcional, mas torna a intenção mais clara.
ALIAS cAliasCaractereOpcional
Alias da tabela usada pelo componente.
FIELDSIZES / SIZES / COLSIZESNuméricoOpcional
Larguras das colunas criadas automaticamente, informadas na mesma ordem dos campos.
HEAD / HEADER / HEADERSCaractereOpcional
Títulos das colunas criadas automaticamente, informados na mesma ordem dos campos.
SIZE nWidth, nHeightNuméricoOpcional
Largura e altura do componente.
OF oDlgObjetoOpcional
Diálogo, painel, folder ou outro contêiner visual proprietário do browse. OF é a forma recomendada na documentação oficial.
SELECT cField FOR uValue1 [TO uValue2]FiltroOpcional
Define um filtro por valor ou intervalo para um campo quando o browse utiliza uma tabela.
ON CHANGE / ON DBLCLICK / ON RIGHT CLICKEventoOpcional
Ações executadas na mudança de linha, no duplo clique ou no clique direito.
FONT · CURSOR · COLOR · MESSAGE · PIXEL · WHEN · VALIDCláusulasOpcional
Personalizam fonte, cursor, cores, dica, coordenadas, recebimento de foco e validação.
Browse baseado em array
#Include "TOTVS.ch"
#Include "tcbrowse.ch"
User Function ExBrowseArray()
Local oDlg
Local oBrowse
Local aClientes := { ;
{"000001", "Cliente Alfa", 1500.00}, ;
{"000002", "Cliente Beta", 2750.50} ;
}
Define Dialog oDlg Title "Clientes" ;
From 180, 180 To 600, 650 Pixel
@ 1, 1 Browse oBrowse Size 220, 156 ;
On DblClick MostrarCliente(oBrowse, aClientes) ;
Of oDlg Pixel
oBrowse:SetArray(aClientes)
Add Column To oBrowse Array Element 1 ;
Header "Código" Size 60
Add Column To oBrowse Array Element 2 ;
Header "Nome" Size 110
Add Column To oBrowse Array Element 3 ;
Header "Valor" Size 70 Picture "@E 99,999,999.99"
Activate Dialog oDlg Centered
Return
Static Function MostrarCliente(oBrowse, aClientes)
MsgInfo(aClientes[oBrowse:nAt, 2])
ReturnResultado esperado
SetArray() associa os dados e cada ADD COLUMN informa qual elemento do array será apresentado. nAt identifica a linha atual.
Browse ligado a uma tabela
#Include "TOTVS.ch"
#Include "tcbrowse.ch"
User Function ExBrowseTabela()
Local oDlg
Local oBrowse
DbSelectArea("SA1")
SA1->(DbGoTop())
Define Dialog oDlg Title "Cadastro de clientes" ;
From 0, 0 To 300, 600 Pixel
@ 10, 10 Browse oBrowse ;
Fields SA1->A1_COD, SA1->A1_NOME ;
Alias "SA1" ;
Headers "Código", "Nome" ;
ColSizes 60, 180 ;
Size 270, 120 Of oDlg Pixel
Activate Dialog oDlg Centered
ReturnResultado esperado
O alias fornece a origem dos registros, enquanto FIELDS, HEADERS e COLSIZES definem as colunas automáticas.
- Inclua tcbrowse.ch; exemplos que utilizam diálogo também costumam incluir TOTVS.ch.
- Para tabelas, FIELDS, HEADERS e COLSIZES permitem que as colunas sejam criadas automaticamente.
- Para arrays, crie o browse, chame SetArray() e adicione colunas com ADD COLUMN TO ... ARRAY ELEMENT ou com TCColumn e AddColumn().
- Prefira OF para explicitar o contêiner proprietário do componente.
- Mantenha a quantidade e a ordem de campos, cabeçalhos e tamanhos coerentes.
- Use os métodos GoUp(), GoDown(), GoTop() e GoBottom() para navegação programática.
- Um browse baseado em array não recebe os dados apenas na declaração: o array precisa ser associado com SetArray().
- Listas de FIELDS, HEADERS e COLSIZES com quantidades ou ordens divergentes produzem colunas incorretas.
- Sem OF, o componente será associado à janela ou ao diálogo ativo no momento.
- Misturar coordenadas PIXEL com outra unidade pode posicionar ou dimensionar o browse incorretamente.
- Eventos muito extensos tornam a interface difícil de manter; encaminhe a ação para uma função dedicada.
- TCBrowse é um componente visual de uso histórico; confirme compatibilidade com o contexto de execução e considere FWBrowse ou FWMBrowse quando o framework for mais adequado.