syntax-highlighting/docs/qml-api.md

0001 Syntax Highlighting QML API   {#qml_api}
0002 ==================
0003
0004 -   [Basic Highlighting](#basic_highlighting)
0005 -   [Advanced Use](#advanced_use)
0006 -   [Further References](#refs)
0007
0008 <a name="basic_highlighting">
0009
0010 ## Basic Highlighting
0011
0012 If all you need is doing syntax highlighting for a fixed language and using a color
0013 theme matching the current system palette this is a matter of adding the `SyntaxHighlighter`
0014 component from the `org.kde.syntaxhighlighting` QML module to a text control.
0015
0016 ~~~
0017 import QtQuick.Controls 2.15
0018 import org.kde.syntaxhighlighting 1.0
0019
0020 TextArea {
0021     text: "..."
0022     SyntaxHighlighter {
0023         id: myHighlighter
0024         textEdit: parent
0025         definition: "C++"
0026     }
0027 }
0028 ~~~
0029
0030 <a name="advanced_use">
0031
0032 ## Advanced Use
0033
0034 For more complex uses the syntax definition might not be fixed but depend on input data (e.g.
0035 derived from its mimetype or file name), or a user selection. In the C++ API this is enabled
0036 by the `Repository` class, which is now also available in QML as a singleton object.
0037
0038 The following example shows how to use this for a simple syntax selection combo box.
0039
0040 ~~~
0041 ComboBox {
0042     model: Repository.definitions
0043     displayText: currentValue.translatedName + " (" + currentValue.translatedSection + ")"
0044     textRole: "translatedName"
0045     onCurrentIndexChanged: myHighlighter.definition = currentValue
0046 }
0047 ~~~
0048
0049 Handling color themes is also possible, similarly to syntax definitions. Themes can be listed,
0050 their properties can be accessed and they can be set by theme object or name on the highlighter.
0051 Like in the C++ API it's also possible to just ask for the light or dark default theme.
0052
0053 <a name="refs">
0054
0055 ## Further References
0056
0057 There's a more complete and pure-QML example in `examples/qml/example.qml` provided as part of
0058 the KSyntaxHighlighting source code that can be run with `qmlscene`.