codeeditor — u_pbt_codeeditor #

← Referência dos componentes · Índice do guia

Editor de código com realce de sintaxe: dez linguagens, números de linha, dobragem de regiões, pesquisa e substituição, marcadores de diagnóstico na calha e largada de ficheiros.

▶ Ver ao vivo — Aplicação de demonstração, mosaico Code editor: a pré-visualização, o código que o produz e esta página, lado a lado.

Em resumo #

Início rápido #

// event open da window
uo_editor.is_syntax = uo_editor.SYNTAX_SQL
uo_editor.is_text   = "SELECT c.name, SUM(o.amount) AS total~r~n" &
                       + "FROM customer c~r~n" &
                       + "WHERE o.status = 'paid'"

// Local variables
string ls_sql

// Reler o que o utilizador introduziu realmente
ls_sql = uo_editor.of_get_text()

is_text devolve o mesmo: aquilo que o utilizador escreve chega lá assim que a escrita assenta (event ue_changed).

Linguagens reconhecidas #

is_syntax aceita uma destas constantes, ou SYNTAX_NONE (cadeia vazia) para texto simples sem realce.

As linguagens de uma mesma família partilham o realce (SYNTAX_JAVA colore como SYNTAX_C, SYNTAX_XML como SYNTAX_HTML): a constante escolhida documenta a intenção do programador, mas o resultado no ecrã é o mesmo. O valor não distingue maiúsculas de minúsculas e um nome desconhecido recai no texto simples, sem erro.

Propriedades #

Conteúdo e linguagem #

Apresentação #

Navegação e interações #

Métodos #

Eventos #

Teclado #

A coluna indicada por ue_caret_changed e il_caret_column é a posição do carácter na sua linha: uma tabulação conta como um, seja qual for a sua largura no ecrã.

Exemplos #

Um editor de consultas SQL #

// Congelar o desenho durante a configuracao
uo_query.of_set_redraw(/*on*/ false)

// Coloracao SQL, depois a consulta a mostrar
uo_query.is_syntax = uo_query.SYNTAX_SQL
uo_query.is_text   = "-- Melhores clientes por volume de negocios recebido~r~n" &
                       + "SELECT c.name, SUM(o.amount) AS total~r~n" &
                       + "FROM customer c~r~n" &
                       + "  INNER JOIN orders o ON o.cust_id = c.id~r~n" &
                       + "WHERE o.status = 'paid'~r~n" &
                       + "GROUP BY c.name~r~n" &
                       + "ORDER BY total DESC"

// Um so redesenho, tudo de uma vez
uo_query.of_set_redraw(/*on*/ true)

// event clicked de cb_execute
string ls_sql

// Executar a consulta tal como foi introduzida
ls_sql = uo_query.of_get_text()     // o que o utilizador introduziu realmente
of_execute(ls_sql)

Um visualizador só de leitura #

Ideal para apresentar código gerado, um registo ou um excerto que o utilizador deve ler sem o modificar.

// Coloracao PowerScript
uo_preview.is_syntax = uo_preview.SYNTAX_POWERSCRIPT

// Um visualizador so de leitura: sem cursor, sem margem, sem realce
uo_preview.ib_readonly     = true      // apenas consulta, sem cursor de escrita
uo_preview.ib_line_numbers = false     // oculta a calha de numeros
uo_preview.ib_current_line = false     // sem realce da linha atual
uo_preview.ib_wrap         = true      // muda de linha em vez de deslocar
uo_preview.ii_tab_size     = 2         // tabulacoes apresentadas em 2 colunas

// O codigo a mostrar
uo_preview.is_text = of_generate_code()

Acompanhar a posição do cursor numa barra de estado #

// Notificar cada movimento do cursor (ue_caret_changed)
uo_editor.ib_track_caret = true       // subscricao explicita: caso contrario nenhum evento

// event ue_caret_changed de uo_editor : (long al_line, long al_col)
uo_status.of_panel(/*key*/ "pos").is_text = "Linha " + String(al_line) + ", col. " + String(al_col)

Sem ib_track_caret, o cursor não comunica nada: este acionador é de frequência elevada e permanece desligado enquanto não for pedido.

Pesquisar e ir para uma linha #

// Abre a barra de pesquisa e realca todas as ocorrencias
uo_editor.of_find(/*text*/ "ll_total")

// event ue_find_result de uo_editor : (long al_count, long al_index)
if al_count = 0 then
    uo_status.of_panel(/*key*/ "main").is_text = "Nenhuma ocorrência"
else
    uo_status.of_panel(/*key*/ "main").is_text = String(al_index) + " / " + String(al_count)
end if

// Ir para a linha que um compilador assinalou e marca-la na calha
uo_editor.of_add_marker(/*line*/ ll_error_line, /*kind*/ uo_editor.MARKER_ERROR, /*tooltip*/ ls_error_text)
uo_editor.il_caret_line = ll_error_line     // o cursor vai para la, a linha vem para o ecra
uo_editor.of_focus_webview()                // o utilizador corrige de imediato

Abrir um ficheiro largado a partir do Explorador #

// Accept files dropped from the Explorer
uo_editor.ib_allow_drop = true

// event ue_drop_files de uo_editor : (string as_files[])
string ls_content
integer li_file

// as_files[1] transporta o caminho COMPLETO do primeiro ficheiro largado
li_file = FileOpen(as_files[1], StreamMode!, Read!)
if li_file > 0 then
    FileReadEx(li_file, ls_content)
    FileClose(li_file)

    // Colorir pela extensao do ficheiro e mostrar o seu conteudo
    uo_editor.is_syntax = of_syntax_for_extension(as_files[1])
    uo_editor.is_text   = ls_content
end if

Reagir às modificações #

// event ue_changed de uo_editor : ( )
cb_save.enabled = uo_editor.ib_modified     // anular ate ao texto guardado repoe-no a false

// event clicked de cb_save
if of_save_script(uo_editor.is_text) = 1 then
    uo_editor.ib_modified = false     // o texto guardado passa a ser a referencia
    cb_save.enabled = false
end if

O evento só é despoletado depois de a escrita estabilizar: uma introdução contínua não gera um evento por cada tecla.

Mudar o nome de uma variável em todo o script #

// Local variables
long ll_count

// So palavras inteiras: ll_total2 e outra variavel
uo_editor.ib_find_whole_word = true
ll_count = uo_editor.of_replace_all(/*find*/ "ll_total", /*replace*/ "ldc_amount")   // um unico Ctrl+Z anula tudo

Boas práticas #

• Definir sempre is_syntax antes de is_text: o código é realçado logo na primeira apresentação, sem que se veja um novo realce.
• Para uma apresentação em modo de consulta, a combinação ib_readonly + ib_line_numbers = false + ib_wrap produz um visualizador sóbrio, que deixa de parecer um editor.
• Para recuperar o que foi introduzido, ler is_text (ou of_get_text()) assim que a escrita assentar — ou seja, dentro do seu ue_changed, que lhe diz quando.
• ib_folding só tem interesse em ficheiros longos e estruturados; deve manter-se desligado para excertos curtos. Desligue-o antes de permitir alterações: um esquema dobrado lê-se, não se edita, e of_get_text() devolve sempre o código-fonte inteiro, regiões fechadas incluídas.
• O carregamento de um ficheiro grande deve ser enquadrado por of_set_redraw(false) / of_set_redraw(true).
• Chamar of_reset() antes de carregar um documento de outra natureza: caso contrário, a linguagem, o tamanho de tabulação ou o modo só de leitura anteriores mantêm-se em vigor.
• Depois de guardar, reponha ib_modified a false: volta a true à primeira tecla, e a false se o utilizador anular até ao texto guardado.
• Para mostrar os erros de uma compilação, of_clear_markers() e depois um of_add_marker por diagnóstico, e il_caret_line no primeiro.

Herdado da base comum #

Estes membros existem em todos os componentes visuais — não são próprios deste. São detalhados uma só vez, nos capítulos transversais; esta tabela apenas diz onde os ler.

Duas ajudas não são herdadas: of_icon e of_escape_markup vivem em n_pbt_utils. Declare um — n_pbt_utils lnv_utils, nada a criar — e chame-as nele.

← Referência dos componentes · Índice do guia