codeeditor — u_pbt_codeeditor #

← Referencia de componentes · Índice de la guía

Editor de código con resaltado de sintaxis: diez lenguajes, números de línea, plegado de regiones, búsqueda y reemplazo, marcadores de diagnóstico en el margen y arrastre de archivos.

▶ Verlo en vivo — Aplicación de demostración, mosaico Code editor: la vista previa, el código que lo genera y esta página, uno al lado del otro.

De un vistazo #

Inicio rápido #

// event open de la ventana
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" &
                       + "  INNER JOIN orders o ON o.cust_id = c.id~r~n" &
                       + "WHERE o.status = 'paid'~r~n" &
                       + "GROUP BY c.name"

// Local variables
string ls_sql

// Releer lo que el usuario ha escrito realmente
ls_sql = uo_editor.of_get_text()

is_text devuelve lo mismo: lo que escribe el usuario llega ahí en cuanto la escritura se asienta (event ue_changed).

Lenguajes reconocidos #

is_syntax acepta una de estas constantes, o SYNTAX_NONE (cadena vacía) para texto sin formato, sin resaltado.

Los lenguajes de una misma familia comparten el resaltado (SYNTAX_JAVA colorea como SYNTAX_C, SYNTAX_XML como SYNTAX_HTML): la constante que elija documenta su intención, el resultado en pantalla es el mismo. El valor no distingue mayúsculas de minúsculas y un nombre desconocido recurre al texto sin formato, sin error. is_syntax se relee exactamente como se escribió, mayúsculas incluidas: "SQL" sigue siendo "SQL".

Propiedades #

Contenido y lenguaje #

Visualización #

Navegación e interacciones #

Métodos #

Eventos #

Teclado #

La columna que indican ue_caret_changed e il_caret_column es la posición del carácter en su línea: una tabulación cuenta como uno, sea cual sea su anchura en pantalla.

Ejemplos #

Un editor de consultas SQL #

// Congelar el dibujo durante la configuracion
uo_query.of_set_redraw(/*on*/ false)

// Coloreado SQL y luego la consulta que mostrar
uo_query.is_syntax = uo_query.SYNTAX_SQL
uo_query.is_text   = "-- Mejores clientes por facturacion cobrada~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"

// Un solo redibujado, todo a la vez
uo_query.of_set_redraw(/*on*/ true)

// event clicked de cb_execute
// Local variables
string ls_sql

// Ejecutar la consulta tal como se escribio
ls_sql = uo_query.of_get_text()     // lo que el usuario ha escrito realmente
of_execute(ls_sql)

Un visor de solo lectura #

Ideal para presentar código generado, un registro o un extracto que el usuario debe leer sin modificarlo.

// Coloreado PowerScript
uo_preview.is_syntax = uo_preview.SYNTAX_POWERSCRIPT

// Un visor de solo lectura: sin cursor, sin margen, sin resaltado
uo_preview.ib_readonly     = true      // solo consulta, sin cursor de escritura
uo_preview.ib_line_numbers = false     // oculta el margen de numeros
uo_preview.ib_current_line = false     // sin resaltado de la linea actual
uo_preview.ib_wrap         = true      // ajusta al ancho en vez de desplazarse
uo_preview.ii_tab_size     = 2         // tabulaciones mostradas en 2 columnas

// El codigo que mostrar
uo_preview.is_text = of_generate_code()

Seguir la posición del cursor en una barra de estado #

// Notificar cada movimiento del cursor (ue_caret_changed)
uo_editor.ib_track_caret = true       // suscripcion explicita: si no, ningun evento

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

Sin ib_track_caret, el cursor no informa de nada: este disparador es de frecuencia elevada y permanece desactivado mientras no lo solicite.

Buscar e ir a una línea #

// Abre la barra de busqueda y resalta todas las apariciones
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 = "Ninguna aparición"
else
    uo_status.of_panel(/*key*/ "main").is_text = String(al_index) + " / " + String(al_count)
end if

// Local variables
long ll_error_line
string ls_error_text
n_pbt_utils lnv_utils

// Lo que dijo el compilador, y donde (lo proporciona su paso de compilacion)
ll_error_line = 39

// El mensaje pasa por of_escape_markup : sus corchetes se muestran tal cual
ls_error_text = lnv_utils.of_escape_markup(/*text*/ "C0031 : Syntax error near ls_names[1]")

// Ir a la linea que ha senalado un compilador y marcarla en el margen
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     // el cursor va alli, la linea llega a la pantalla
uo_editor.of_focus_webview()                // el usuario corrige enseguida

Abrir un archivo soltado desde el Explorador #

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

// event ue_drop_files de uo_editor : (string as_files[])
// Local variables
blob lblb_content
integer li_file

// as_files[1] lleva la ruta COMPLETA del primer archivo soltado
li_file = FileOpen(as_files[1], StreamMode!, Read!)
if li_file > 0 then
    FileReadEx(li_file, lblb_content)
    FileClose(li_file)

    // Colorear segun la extension del archivo y mostrar su contenido
    uo_editor.is_syntax = of_syntax_for_extension(as_files[1])

    // Los bytes del archivo, leidos como texto UTF-8 (la codificacion de los fuentes de hoy)
    uo_editor.is_text   = String(lblb_content, EncodingUTF8!)
end if

Reaccionar a las modificaciones #

// event ue_modified_changed de uo_editor : (boolean ab_modified)
cb_save.enabled = ab_modified     // deshacer hasta el texto guardado lo devuelve a false

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

ue_modified_changed se lanza enseguida, en la primera pulsación como en el deshacer que vuelve al texto guardado. Escribir ib_modified o un nuevo is_text no lanza nada: su código ya lo sabe. ue_changed, en cambio, espera a que la escritura se haya asentado.

Botones Deshacer y Rehacer #

// event ue_undo_state_changed de uo_editor : (boolean ab_can_undo, boolean ab_can_redo)
// Los botones siguen lo que el historial puede hacer
cb_undo.enabled = ab_can_undo
cb_redo.enabled = ab_can_redo

// event clicked de cb_undo
// El mismo paso que Ctrl+Z ; el foco vuelve al codigo
uo_editor.of_undo()
uo_editor.of_focus_webview()

Un editor que es solo un campo de un formulario #

// Un filtro SQL escrito en un formulario
uo_filter.is_syntax = uo_filter.SYNTAX_SQL

// Tab pasa al campo siguiente, como en todas partes
uo_filter.ib_tab_moves_focus = true

Sin esta propiedad, Esc y luego Tab o Ctrl+M siguen dejando salir al usuario con el teclado: el editor nunca atrapa el teclado.

Renombrar una variable en todo el script #

// Local variables
long ll_count

// Solo palabras completas: ll_total2 es otra variable
uo_editor.ib_find_whole_word = true
ll_count = uo_editor.of_replace_all(/*find*/ "ll_total", /*replace*/ "ll_amount")   // un solo Ctrl+Z lo deshace todo

Buenas prácticas #

• Asigne siempre is_syntax antes que is_text: el código aparece coloreado desde la primera visualización, sin recoloración visible.
• Para una presentación en modo consulta, la combinación ib_readonly + ib_line_numbers = false + ib_wrap da un visor sobrio que ya no parece un editor.
• Para recuperar lo escrito, lea is_text (o of_get_text()) una vez asentada la escritura, — es decir, dentro de su ue_changed, que le dice cuándo.
• ib_folding solo resulta interesante en archivos largos y estructurados; déjelo desactivado para extractos breves. Apáguelo antes de permitir modificaciones: un esquema plegado se lee, no se edita, y of_get_text() devuelve siempre el código fuente completo, regiones cerradas incluidas.
• Enmarque la carga de un archivo grande con of_set_redraw(false) / of_set_redraw(true).
• Llame a of_reset() antes de cargar un documento de otra naturaleza: sin ello, el lenguaje, el tamaño de tabulación o el modo de solo lectura anteriores siguen vigentes.
• Tras guardar, vuelva a poner ib_modified en false: vuelve a ser true en la primera pulsación, y false si el usuario deshace hasta el texto guardado.
• Para mostrar los errores de una compilación, of_clear_markers() y luego un of_add_marker por diagnóstico, e il_caret_line en el primero.
• En un formulario donde el editor es solo un campo entre otros, ponga ib_tab_moves_focus = true: Tab pasa entonces al campo siguiente, como en todas partes.
• Para botones Deshacer / Rehacer, siga ue_undo_state_changed y llame a of_undo / of_redo: el historial es el de Ctrl+Z, y también cuenta lo que hace su código.

Heredado de la base común #

Estos miembros existen en todos los componentes visuales — no son propios de este. Se detallan una sola vez, en los capítulos transversales; esta tabla solo dice dónde leerlos.

Dos ayudas no se heredan: of_icon y of_escape_markup viven en n_pbt_utils. Declare uno — n_pbt_utils lnv_utils, nada que crear — y llámelas sobre él.

← Referencia de componentes · Índice de la guía