From 578b88fa29f210bac0df04b92dedba8004c02c32 Mon Sep 17 00:00:00 2001 From: Rosemoe <2073412493@qq.com> Date: Mon, 12 Feb 2024 17:33:36 +0800 Subject: [PATCH] docs(en): add basic usage in getting-started --- guide/getting-started.md | 72 ++++++++++++++++++++++++++++++++++++---- 1 file changed, 65 insertions(+), 7 deletions(-) diff --git a/guide/getting-started.md b/guide/getting-started.md index ae29244..40b6042 100644 --- a/guide/getting-started.md +++ b/guide/getting-started.md @@ -8,7 +8,7 @@ Before including [sora-editor](https://github.com/Rosemoe/sora-editor) library i * The minimum Android SDK version of your module is at least Android L (API 21) * If you are to use [Language Server Protocol](https://microsoft.github.io/language-server-protocol/), the requirement will be at least Android O (API 26) * Project Java source compatibility and target compatibility is `JavaVersion.VERSION_17` -::: details Set Java Compile and Target Compatibilities +::: details Set Java Source and Target Compatibilities ::: code-group @@ -126,10 +126,31 @@ Check the table below to get more information about the modules. | language-java | A simple implementation for Java lexer-based highlighting and identifier auto-completion | | language-textmate | An advanced highlighter for the editor. It can be used to load TextMate language bundles and themes. The internal implementation of TextMate is from [tm4e](https://github.com/eclipse/tm4e) | | language-treesitter | Offer [tree-sitter](https://tree-sitter.github.io/tree-sitter/) support for editor. This can be used to parse the code to an AST fast and incrementally, which is helpful for accurate highlighting and providing completions. Note that this module only provides incremental parsing and highlighting. Thanks to Java bindings [android-tree-sitter](https://github.com/AndroidIDEOfficial/android-tree-sitter/) | +### 🚧Snapshot Builds + +Generally, it is recommended to use [released versions](https://github.com/Rosemoe/sora-editor/releases). But sometimes you may still want to use nightly builds for latest bug fixes and enhancements. + +::: details How to Use Snapshot Builds + +Snapshot versions are automatically published on repository push. You may combine current released version name +and short commit hash to make a snapshot version name. + +For example, if the latest released version name is '0.21.1' and +short commit hash is '97c4963', you may use version name '0.21.1-97c4963-SNAPSHOT' to import the snapshot version to your project. + +Note that adding extra maven repository is required: +```Kotlin{3} +repositories { + // ... + maven("https://s01.oss.sonatype.org/content/repositories/snapshots") +} +``` + +::: ## Configure Desugaring for TextMate -If you use `language-textmate` module in your project, and want to run the application on devices under Android N (API 24), you **must** enable core library desugaring to avoid compatibility issues. Otherwise, you can go on to next section. +If you use `language-textmate` module in your project, and want to run the application on devices under Android N (API 24), you **must** enable [Core Library Desugaring](https://developer.android.google.cn/studio/write/java8-support#library-desugaring) to avoid compatibility issues. Otherwise, you can go on to next section. To enable the desugaring, follow the instructions below to setup your **application module**. @@ -175,11 +196,48 @@ android { Please ensure you have included `editor` module in your project, and then sync your project with Gradle files successfully. -The main widget class is `io.github.rosemoe.sora.widget.CodeEditor`. You can create the code editor either by XML or Java/Kotlin code. - -```Xml +The main widget class is `io.github.rosemoe.sora.widget.CodeEditor`. You can create the code editor either by XML or Java/Kotlin code(recommended). Only limited editor attributes can be set in XML. +### Use in XML +Declare editor in your layout XML files: +```XML -``` \ No newline at end of file + android:layout_height="match_parent" + app:text="Hello, world!" + app:textSize="18sp" /> +``` +It's not necessary to set `text` or `textSize` in XML declaration. + +Refer to [XML Attributes]() for more information about its usage in XML. +::: tip NOTE +It is not recommended to use `wrap_content` for editor width or height. In that case, when the text is editted, the editor has to request re-layout which probably causes lags. +::: +### Use in Java/Kotlin code +Just create a editor and add it to any view group. Supposing we are in any `Activity` context, and `vg` is a `ViewGroup` instance. +::: code-group +```Kotlin [Kotlin] +val editor = CodeEditor(this) +editor.setText("Hello, world!") // Set text +editor.typefaceText = Typeface.MONOSPACE // Use Monospace Typeface +editor.nonPrintablePaintingFlags = + CodeEditor.FLAG_DRAW_WHITESPACE_LEADING or CodeEditor.FLAG_DRAW_LINE_SEPARATOR or CodeEditor.FLAG_DRAW_WHITESPACE_IN_SELECTION // Show Non-Printable Characters +vg.add(editor, ViewGroup.LayoutParams(ViewGroup.LayoutParams.MATCH_PARENT, ViewGroup.LayoutParams.MATCH_PARENT)) +``` +```Java [Java] +var editor = new CodeEditor(this); +editor.setText("Hello, world!"); // Set Text +editor.setTypefaceText(Typeface.MONOSPACE); // Use Monospace Typeface +editor.setNonPrintablePaintingFlags( + CodeEditor.FLAG_DRAW_WHITESPACE_LEADING | CodeEditor.FLAG_DRAW_LINE_SEPARATOR | CodeEditor.FLAG_DRAW_WHITESPACE_IN_SELECTION); // Show Non-Printable Characters +vg.add(editor, new ViewGroup.LayoutParams(ViewGroup.LayoutParams.MATCH_PARENT, ViewGroup.LayoutParams.MATCH_PARENT)); +``` +::: +Please view methods of `CodeEditor` and fields of `DirectAccessProps` for more attributes you can configure. +::: warning BE CAUTIOUS +Not all fields of `DirectAccessProps` can take effect without invalidation. Call `invalidate()` on editor after changing those fields marked with `@InvalidateRequired`. + +Methods and fields that marked with `@UnsupportedUserUsage` should not be used. They are visible for internal access. +::: +## Continue +Go to [Languages](/language.md) and [Color Scheme](/color-scheme.md) to equip the editor with programming language support and your custom color scheme. \ No newline at end of file