TelamonCodeEditor

TelamonCodeEditor edits plain text in the monospace font, coloured by KSyntaxHighlighting for the language you give it (language) or that the file name implies (fileName). The colours come from the Telamon theme and follow Light, Dark and high contrast. It has a line-number gutter, tints the caret's row, and can mark lines an app changed (markLines). For a read-only view of a log or a command's output use TelamonCodeView or TelamonConsoleView.

Lines are numbered from 1 in the whole API: cursorLine, scrollToLine(), markLines(), firstVisibleLine.

setTextPreserving() is for text that changes under the reader, such as an assistant's edit of the open file: it rewrites only what differs and leaves the caret, the selection and the scroll position where they were.

Example

TelamonCodeEditor {
    anchors.fill: parent
    fileName: "main.rs"
    text: source
    onTextEdited: dirty = true
}

An edit that arrives from outside, with the changed lines marked for a moment:

editor.setTextPreserving(newSource)
editor.markLines([[12, 18], 40], TelamonCodeEditor.Changed, 3000)
editor.scrollToLine(12)

What the text is

• Plain text only. Nothing in the text is taken as HTML or Markdown, and a link in it is not a link. The text field is a plain text field.
• Line breaks read back as LF. CR, CRLF and U+2029 in a text you set become \n. An app that must keep CRLF files converts them back when it saves. Other characters, a no-break space included, come back as they went in. The two code points U+FDD0 and U+FDD1, which the text engine reads as frame markers, are replaced by U+FFFD.
• Bidirectional controls are shown. The editor draws the text as it is, so a file with bidirectional control characters (U+202A to U+202E, U+2066 to U+2069) can show its code in another order than the compiler reads it. The characters are kept so that a save changes nothing; an app that opens files it does not trust should look for them in text and tell the user.
• Setting text loads a document. The undo history is cleared, the marks are cleared and modified is false. textEdited is not emitted: it tells the app about the user's edits only.

Large files

Qt's text engine lays out a line in about 70 microseconds, redraws in time proportional to the number of lines at each change (about 8 ms per 1,000 lines on the software renderer) and uses about 75 MB of memory per MiB of text. Typing in a text of a few thousand lines is smooth; at 15,000 lines (about 1 MiB) a change takes about 120 ms to draw, at 100,000 lines most of a second. That is why maximumSize is 1 MiB by default and why a larger text goes to the viewer. An app can raise it for files it knows are worth the cost.

Setting a big text does not stop the window: a text of more than 64 KiB is put into the document a few lines at a time from the event loop (about 0.8 s for 900 KiB, with no stall over about 110 ms). loading is true meanwhile, text already returns all of it, the editor is read-only (the lines that have arrived can be scrolled and selected), and loaded() is emitted at the end. Setting another text or calling setTextPreserving() while it loads starts over.

The editor never hands a text it cannot edit smoothly to the text field. A text is "too large" when it has more than maximumSize characters (1 MiB by default), or a line longer than 200,000 characters. It is then shown in a read-only viewer (TelamonTextView, built for any size) under a note that says why. tooLarge is true, text still returns the text, modified stays false and typing does nothing. The marks are not drawn. Setting a text under the limits makes the editor editable again.

Highlighting is lazy: only the lines in view, and a margin around them, are coloured, and the lines above them are read in short slices from the event loop, so opening a big file never stops the window. A line longer than 4,000 characters is left unhighlighted (a regular expression over a line that long is a stall); the lines around it are coloured as usual.

Keyboard

In a read-only editor Tab moves the focus on.

Accessibility

Screen readers get the text field, named "Code editor". Set Accessible.name on the editor to say which file it holds ("main.rs"). The keyboard focus ring shows only for keyboard focus. Marked lines are told apart by more than colour: an added line has a solid gutter bar, a changed one a dashed bar. In high contrast the syntax is shown without colour: keywords are bold, comments italic.

Properties

Enumerations

The values of the kind of markLines():

Signals

Methods