codeeditor — u_pbt_codeeditor #

← Komponentenreferenz · Inhalt des Handbuchs

Code-Editor mit Syntaxhervorhebung: zehn Sprachen, Zeilennummern, Falten von Regionen, Suchen und Ersetzen, Diagnosemarkierungen in der Leiste und Ablegen von Dateien.

▶ Live ansehen — Demoanwendung, Kachel Code editor: die Vorschau, der zugehörige Code und diese Seite, nebeneinander.

Auf einen Blick #

Schnellstart #

// open-Event des Fensters
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

// Zuruecklesen, was der Benutzer tatsaechlich eingegeben hat
ls_sql = uo_editor.of_get_text()

is_text liefert dasselbe: Die Eingabe des Benutzers landet dort, sobald sie sich gesetzt hat (Event ue_changed).

Unterstützte Sprachen #

is_syntax akzeptiert eine dieser Konstanten oder SYNTAX_NONE (leere Zeichenkette) für reinen Text ohne Hervorhebung.

Sprachen derselben Familie teilen sich die Hervorhebung (SYNTAX_JAVA färbt wie SYNTAX_C, SYNTAX_XML wie SYNTAX_HTML): Die Konstante, die Sie wählen, dokumentiert Ihre Absicht, das Ergebnis auf dem Bildschirm ist dasselbe. Der Wert unterscheidet nicht zwischen Groß- und Kleinschreibung, und ein unbekannter Name fällt ohne Fehler auf reinen Text zurück. is_syntax wird genau so zurückgelesen, wie es geschrieben wurde, Groß- und Kleinschreibung eingeschlossen: "SQL" bleibt "SQL".

Eigenschaften #

Inhalt und Sprache #

Anzeige #

Navigation und Interaktionen #

Methoden #

Events #

Tastatur #

Die Spalte, die ue_caret_changed und il_caret_column melden, ist der Rang des Zeichens in seiner Zeile: ein Tabulator zählt als eins, unabhängig von seiner Breite auf dem Bildschirm.

Beispiele #

Ein Editor für SQL-Abfragen #

// Das Zeichnen waehrend der Einrichtung anhalten
uo_query.of_set_redraw(/*on*/ false)

// SQL-Hervorhebung, dann die anzuzeigende Abfrage
uo_query.is_syntax = uo_query.SYNTAX_SQL
uo_query.is_text   = "-- Beste Kunden nach vereinnahmtem Umsatz~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"

// Ein einziges Neuzeichnen, alles auf einmal
uo_query.of_set_redraw(/*on*/ true)

// clicked-Event von cb_execute
// Local variables
string ls_sql

// Die Abfrage so ausfuehren, wie sie eingegeben wurde
ls_sql = uo_query.of_get_text()     // die tatsaechliche Eingabe des Benutzers
of_execute(ls_sql)

Ein schreibgeschützter Betrachter #

Ideal, um generierten Code, ein Protokoll oder einen Auszug zu zeigen, den der Benutzer lesen, aber nicht ändern soll.

// PowerScript-Hervorhebung
uo_preview.is_syntax = uo_preview.SYNTAX_POWERSCRIPT

// Ein reiner Betrachter: kein Cursor, keine Leiste, keine Hervorhebung
uo_preview.ib_readonly     = true      // nur lesen, keine Einfuegemarke
uo_preview.ib_line_numbers = false     // blendet die Nummernleiste aus
uo_preview.ib_current_line = false     // keine Hervorhebung der aktuellen Zeile
uo_preview.ib_wrap         = true      // bricht um, statt zu scrollen
uo_preview.ii_tab_size     = 2         // Tabulatoren ueber 2 Spalten dargestellt

// Der anzuzeigende Code
uo_preview.is_text = of_generate_code()

Die Position der Einfügemarke in einer Statusleiste verfolgen #

// Jede Cursorbewegung melden (ue_caret_changed)
uo_editor.ib_track_caret = true       // ausdrueckliches Opt-in : sonst gar kein Event

// ue_caret_changed-Event von uo_editor : (long al_line, long al_col)
uo_status.of_panel(/*key*/ "pos").is_text = "Zeile " + String(al_line) + ", Sp. " + String(al_col)

Ohne ib_track_caret meldet die Einfügemarke nichts: Dieser Auslöser feuert sehr häufig und bleibt abgeschaltet, solange Sie ihn nicht anfordern.

Suchen und zu einer Zeile springen #

// Oeffnet die Suchleiste und hebt alle Vorkommen hervor
uo_editor.of_find(/*text*/ "ll_total")

// ue_find_result-Event von uo_editor : (long al_count, long al_index)
if al_count = 0 then
    uo_status.of_panel(/*key*/ "main").is_text = "Kein Treffer"
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

// Was der Compiler gemeldet hat, und wo (Ihr Build-Schritt liefert es)
ll_error_line = 39

// Die Meldung laeuft durch of_escape_markup : ihre eckigen Klammern erscheinen unveraendert
ls_error_text = lnv_utils.of_escape_markup(/*text*/ "C0031 : Syntax error near ls_names[1]")

// Zu der Zeile gehen, die ein Compiler gemeldet hat, und sie in der Leiste markieren
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     // die Einfuegemarke geht dorthin, die Zeile kommt auf den Bildschirm
uo_editor.of_focus_webview()                // der Benutzer korrigiert sofort

Eine aus dem Explorer abgelegte Datei öffnen #

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

// ue_drop_files-Event von uo_editor : (string as_files[])
// Local variables
blob lblb_content
integer li_file

// as_files[1] traegt den VOLLSTAENDIGEN Pfad der ersten abgelegten Datei
li_file = FileOpen(as_files[1], StreamMode!, Read!)
if li_file > 0 then
    FileReadEx(li_file, lblb_content)
    FileClose(li_file)

    // Nach der Dateiendung hervorheben, dann den Inhalt anzeigen
    uo_editor.is_syntax = of_syntax_for_extension(as_files[1])

    // Die Bytes der Datei, als UTF-8-Text gelesen (die Kodierung heutiger Quelldateien)
    uo_editor.is_text   = String(lblb_content, EncodingUTF8!)
end if

Auf Änderungen reagieren #

// ue_modified_changed-Event von uo_editor : (boolean ab_modified)
cb_save.enabled = ab_modified     // Rueckgaengig bis zum gespeicherten Text setzt ihn auf false zurueck

// clicked-Event von cb_save
if of_save_script(uo_editor.is_text) = 1 then
    uo_editor.ib_modified = false     // der gespeicherte Text wird zur Referenz
    cb_save.enabled = false
end if

ue_modified_changed wird sofort ausgelöst, beim ersten Tastendruck wie beim Rückgängig, das zum gespeicherten Text zurückführt. Das Schreiben von ib_modified oder ein neues is_text löst nichts aus: Ihr Code weiß es bereits. ue_changed wartet dagegen, bis die Eingabe zur Ruhe gekommen ist.

Schaltflächen Rückgängig und Wiederholen #

// ue_undo_state_changed-Event von uo_editor : (boolean ab_can_undo, boolean ab_can_redo)
// Die Schaltflaechen folgen dem, was der Verlauf kann
cb_undo.enabled = ab_can_undo
cb_redo.enabled = ab_can_redo

// clicked-Event von cb_undo
// Derselbe Schritt wie Strg+Z ; der Fokus geht zurueck zum Code
uo_editor.of_undo()
uo_editor.of_focus_webview()

Ein Editor, der nur ein Feld eines Formulars ist #

// Ein SQL-Filter, der in einem Formular eingegeben wird
uo_filter.is_syntax = uo_filter.SYNTAX_SQL

// Tab geht zum naechsten Feld, wie ueberall sonst
uo_filter.ib_tab_moves_focus = true

Ohne diese Eigenschaft lassen Esc und dann Tab oder Strg+M den Benutzer weiterhin über die Tastatur hinaus: der Editor hält die Tastatur nie fest.

Eine Variable im ganzen Skript umbenennen #

// Local variables
long ll_count

// Nur ganze Woerter: ll_total2 ist eine andere Variable
uo_editor.ib_find_whole_word = true
ll_count = uo_editor.of_replace_all(/*find*/ "ll_total", /*replace*/ "ll_amount")   // ein einziges Strg+Z macht alles rueckgaengig

Best Practices #

• Setzen Sie is_syntax immer vor is_text: Der Code ist schon beim ersten Zeichnen eingefärbt, ohne sichtbares Nachfärben.
• Für eine reine Anzeige ergibt die Kombination ib_readonly + ib_line_numbers = false + ib_wrap einen schlichten Betrachter, der nicht mehr wie ein Editor aussieht.
• Um eine Eingabe abzuholen, lesen Sie is_text (oder of_get_text()), sobald die Eingabe sich gesetzt hat, — also in Ihrem ue_changed, das Ihnen sagt, wann.
• ib_folding lohnt sich nur bei langen, strukturierten Dateien; lassen Sie es bei kurzen Auszügen ausgeschaltet. Schalten Sie es aus, bevor Sie Änderungen zulassen: eine gefaltete Gliederung wird gelesen, nicht bearbeitet, und of_get_text() liefert stets die ganze Quelle, geschlossene Regionen eingeschlossen.
• Klammern Sie das Laden einer großen Datei mit of_set_redraw(false) / of_set_redraw(true) ein.
• Rufen Sie of_reset() auf, bevor Sie ein Dokument anderer Art laden: Sonst bleiben die vorherige Sprache, die Tabulatorbreite oder der Schreibschutzmodus bestehen.
• Setzen Sie ib_modified nach dem Speichern auf false zurück: beim ersten Tastendruck wird es wieder true, und false, wenn der Benutzer bis zum gespeicherten Text rückgängig macht.
• Um die Fehler einer Kompilierung zu zeigen: of_clear_markers(), dann ein of_add_marker pro Diagnose und il_caret_line auf die erste.
• In einem Formular, in dem der Editor nur ein Feld unter anderen ist, setzen Sie ib_tab_moves_focus = true: Tab geht dann zum nächsten Feld, wie überall sonst.
• Für Schaltflächen Rückgängig / Wiederholen folgen Sie ue_undo_state_changed und rufen of_undo / of_redo auf: der Verlauf ist der von Strg+Z, und er zählt auch, was Ihr Code tut.

Vom gemeinsamen Sockel geerbt #

Diese Mitglieder gibt es bei jeder visuellen Komponente — sie sind nicht dieser eigen. Sie werden einmal in den übergreifenden Kapiteln beschrieben; diese Tabelle sagt nur, wo man sie liest.

Zwei Helfer werden nicht geerbt: of_icon und of_escape_markup liegen auf n_pbt_utils. Deklarieren Sie eines — n_pbt_utils lnv_utils, nichts zu erzeugen — und rufen Sie sie darauf auf.

← Komponentenreferenz · Inhalt des Handbuchs