Add samples (#262)

* Add samples --------- Co-authored-by: Erwin Morrhey <[email protected]>
gluonhq · Jul 14, 2023 · 1ede593 · 1ede593
1 parent 6185a57
commit 1ede593
Show file tree

Hide file tree

Showing 22 changed files with 965 additions and 32 deletions.
diff --git a/.github/assets/ActionsDemo.png b/.github/assets/ActionsDemo.png
diff --git a/.github/assets/BasicDemo.png b/.github/assets/BasicDemo.png
diff --git a/.github/assets/EmojiDemo.png b/.github/assets/EmojiDemo.png
diff --git a/.github/assets/EmojiPopupDemo.png b/.github/assets/EmojiPopupDemo.png
diff --git a/.github/assets/HighlightDemo.png b/.github/assets/HighlightDemo.png
diff --git a/.github/assets/ListsDemo.png b/.github/assets/ListsDemo.png
diff --git a/README.md b/README.md
@@ -24,6 +24,8 @@ Based on the combination of VirtualFlow and multiple TextFlow controls, the Rich
 - Emoji support
 - … (and more to come)
 
+![rta_editor.png](.github/assets/rta_editor.png)
+
 ### License
 
 The RichTextArea control is available for free under the GPLv3 license. If you create an Open Source application, you can use our software for free.
@@ -34,41 +36,29 @@ The RichTextArea control is available for free under the GPLv3 license. If you c
 To use the RichTextArea control in your project add the following dependency:
 
 ```
-    <dependencies>
-        <dependency>
-            <groupId>com.gluonhq</groupId>
-            <artifactId>rich-text-area</artifactId>
-            <version>1.0.0</version>
-        </dependency>
-    </dependencies>
+<dependency>
+    <groupId>com.gluonhq</groupId>
+    <artifactId>rich-text-area</artifactId>
+    <version>1.0.0</version>
+</dependency>
  ```
 
 and then simply create an instance and add it to your JavaFX application:
 
 ```
-    @Override
-    public void start(Stage stage) {
-        RichTextArea editor = new RichTextArea();
-        BorderPane root = new BorderPane(editor);
-        Scene scene = new Scene(root, 800, 600);
-        stage.setScene(scene);
-        stage.show();
-    }
+@Override
+public void start(Stage stage) {
+    RichTextArea editor = new RichTextArea();
+    BorderPane root = new BorderPane(editor);
+    Scene scene = new Scene(root, 800, 600);
+    stage.setScene(scene);
+    stage.show();
+}
 ```
 
 ### Samples
 
-#### RichTextEditor sample
-
-One possible use of the RichTextArea control is as a RichTextEditor. The sample includes a number of menus and toolbars that allow the user apply actions over selections or at the caret location.
-
-#### Instructions
-
-To run this sample, using Java 17+, do as follows:
-
-    mvn javafx:run -fsamples
-
-![rta_editor.png](.github/assets/rta_editor.png)
+Multiple samples, from basic to full-featured can be found in the [samples folder](samples).
 
 ## Issues and Contributions
 

diff --git a/samples/README.md b/samples/README.md
@@ -0,0 +1,147 @@
+# The RichTextArea Samples
+
+> Note: all instructions assume you changed into the samples folder:
+> ```shell
+> cd samples
+> ```
+
+## BasicDemo
+
+The [BasicDemo](/samples/src/main/java/com/gluonhq/richtextarea/samples/BasicDemo.java) is the most simple use case of 
+the RichTextArea control: it shows a prompt message, and the user can add text.
+
+While all the control features are available, there are no menus or toolbars included, so user interaction is limited 
+to shortcuts or the context menu.
+
+For instance, after typing some text, select all (Ctrl/Cmd + A) or part of it (with mouse or keyboard) and press 
+Ctrl/Cmd + I for italic or Ctrl/Cmd + B for bold.
+
+Undo/Redo, Cut/Copy/Paste options work as usual. You can also copy text with emoji unicode, and paste it on the editor.
+For instance, while running this sample, copy this text:
+
+```
+Hello Rich Text Area 👋🏼
+```
+
+and paste it inside the RichTextArea control, you should see the waving hand emoji and some text. Also copying from
+the control and pasting it on the control itself or on any other application will work
+too, keeping the rich content when possible.
+
+Right click to display a context menu with different options, like inserting a
+2x1 table.
+
+To apply the rest of the control features, some UI is needed for user interaction. See
+the [FullFeaturedDemo](#fullfeatureddemo) sample for a complete and advanced showcase.
+
+### Usage
+
+To run this sample, using Java 17+, do as follows:
+
+```
+mvn javafx:run -Dmain.class=com.gluonhq.richtextarea.samples.BasicDemo
+```
+
+![rta_editor.png](../.github/assets/BasicDemo.png)
+
+## HighlightDemo
+
+The [HighlightDemo](/samples/src/main/java/com/gluonhq/richtextarea/samples/HighlightDemo.java) shows how to use the 
+RichTextArea control to add a document with some decorations, that are generated by searching some keywords over a 
+given text.
+
+### Usage
+
+To run this sample, using Java 17+, do as follows:
+
+```
+mvn javafx:run -Dmain.class=com.gluonhq.richtextarea.samples.HighlightDemo
+```
+
+![rta_editor.png](../.github/assets/HighlightDemo.png)
+
+## ListsDemo
+
+The [ListsDemo](/samples/src/main/java/com/gluonhq/richtextarea/samples/ListsDemo.java) shows a list, generated with 
+custom numbered and bulleted decorations created via `RichTextArea::paragraphGraphicFactoryProperty`.
+
+### Usage
+
+To run this sample, using Java 17+, do as follows:
+
+```
+mvn javafx:run -Dmain.class=com.gluonhq.richtextarea.samples.ListsDemo
+```
+
+![rta_editor.png](../.github/assets/ListsDemo.png)
+
+## ActionsDemo
+
+The [ActionsDemo](/samples/src/main/java/com/gluonhq/richtextarea/samples/ActionsDemo.java) shows how to use the 
+RichTextArea control to render some text and interact with it in a basic way via three toggle buttons.
+
+Run the sample and select some or all text, via mouse or keyboard, and then press the toggles to see how the decoration
+of the selection changes accordingly.
+
+Note that when you move the caret over the text, the toggles update their state 
+(enabled means bold/italic/underline active), showing at any time the current decoration at the caret.
+
+### Usage
+
+To run this sample, using Java 17+, do as follows:
+
+```
+mvn javafx:run -Dmain.class=com.gluonhq.richtextarea.samples.ActionsDemo
+```
+
+![rta_editor.png](../.github/assets/ActionsDemo.png)
+
+## EmojiDemo
+
+The [EmojiDemo](/samples/src/main/java/com/gluonhq/richtextarea/samples/EmojiDemo.java) shows how to use the 
+RichTextArea control to render text and emojis.
+
+This sample doesn't include a control to select interactively emojis (See [EmojiPopupDemo](#emojipopupdemo) for that).
+
+### Usage
+
+To run this sample, using Java 17+, do as follows:
+
+```
+mvn javafx:run -Dmain.class=com.gluonhq.richtextarea.samples.EmojiDemo
+```
+
+![rta_editor.png](../.github/assets/EmojiDemo.png)
+
+## EmojiPopupDemo
+
+The [EmojiPopupDemo](/samples/src/main/java/com/gluonhq/richtextarea/samples/EmojiPopupDemo.java) shows how to use the
+RichTextArea control to render text and emojis, including a popup control to select emojis interactively.
+
+### Usage
+
+To run this sample, using Java 17+, do as follows:
+
+```
+mvn javafx:run -Dmain.class=com.gluonhq.richtextarea.samples.EmojiPopupDemo
+```
+
+![rta_editor.png](../.github/assets/EmojiPopupDemo.png)
+
+## FullFeaturedDemo
+
+The [FullFeaturedDemo](/samples/src/main/java/com/gluonhq/richtextarea/samples/FullFeaturedDemo.java) shows a complete
+use case of the RichTextArea control as a rich text editor. 
+
+This is an advance sample that shows how to create a rich text editor, by using the RichTextArea control and adding
+actions for the user interaction, via toolbars and menus, and most of the features of the control are showcased in this
+sample.
+
+### Usage
+
+To run this sample, using Java 17+, do as follows:
+
+```
+mvn javafx:run
+```
+
+![rta_editor.png](../.github/assets/rta_editor.png)
diff --git a/samples/pom.xml b/samples/pom.xml
@@ -14,7 +14,7 @@
         <maven.compiler.release>11</maven.compiler.release>
         <javafx.version>20</javafx.version>
         <javafx.plugin.version>0.0.8</javafx.plugin.version>
-        <main.class>com.gluonhq.richtextarea.samples.RichTextEditorDemo</main.class>
+        <main.class>com.gluonhq.richtextarea.samples.FullFeaturedDemo</main.class>
         <jpro.version>2022.1.0</jpro.version>
         <rta.version>1.1.0-SNAPSHOT</rta.version>
     </properties>

diff --git a/samples/src/main/java/com/gluonhq/richtextarea/samples/ActionsDemo.java b/samples/src/main/java/com/gluonhq/richtextarea/samples/ActionsDemo.java
@@ -0,0 +1,124 @@
+/*
+ * Copyright (c) 2023, Gluon
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with this program.  If not, see <http://www.gnu.org/licenses/>.
+ *
+ * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
+ * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+ * WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+ * DISCLAIMED. IN NO EVENT SHALL GLUON BE LIABLE FOR ANY
+ * DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
+ * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
+ * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
+ * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+ * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+ * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+ */
+package com.gluonhq.richtextarea.samples;
+
+import com.gluonhq.richtextarea.RichTextArea;
+import com.gluonhq.richtextarea.Selection;
+import com.gluonhq.richtextarea.action.TextDecorateAction;
+import com.gluonhq.richtextarea.model.DecorationModel;
+import com.gluonhq.richtextarea.model.Document;
+import com.gluonhq.richtextarea.model.ParagraphDecoration;
+import com.gluonhq.richtextarea.model.TextDecoration;
+import javafx.application.Application;
+import javafx.event.ActionEvent;
+import javafx.scene.Scene;
+import javafx.scene.control.ToggleButton;
+import javafx.scene.layout.BorderPane;
+import javafx.scene.layout.HBox;
+import javafx.stage.Stage;
+
+import java.util.ArrayList;
+import java.util.List;
+
+import static javafx.scene.text.FontPosture.ITALIC;
+import static javafx.scene.text.FontPosture.REGULAR;
+import static javafx.scene.text.FontWeight.BOLD;
+import static javafx.scene.text.FontWeight.NORMAL;
+
+/**
+ * This sample shows how to use the RichTextArea control to render some text and
+ * interact with it in a basic way via three toggle buttons.
+ * <p>
+ * Run the sample and select some or all text, via mouse or keyboard, and then
+ * press the toggles to see how the decoration of the selection changes accordingly.
+ * <p>
+ * Note that when you move the caret over the text, the toggles update their state
+ * (enabled means bold/italic/underline active), showing at any time the current
+ * decoration at the caret.
+ */
+public class ActionsDemo extends Application {
+
+    private static final String text =
+            "Document is the basic model that contains all the information required for the RichTextArea control, " +
+            "in order to render all the rich content, including decorated text, images and other non-text objects.\n" +
+            "A document is basically a string with the full text, and a list of DecorationModel that contain the text and paragraph decorations for one or more fragments of the text, " +
+            "where a fragment can be defined as the longest substring of the text that shares the same text and paragraph decorations.\n" +
+            "Any change to the document invalidates the undo/redo stack, forces the RichTextAreaSkin to recreate the PieceTable and sets it on the RichTextAreaViewModel.";
+
+    private static final TextDecoration preset =
+            TextDecoration.builder().presets().fontFamily("Arial").fontSize(14).build();
+    private static final ParagraphDecoration parPreset =
+            ParagraphDecoration.builder().presets().build();
+
+    @Override
+    public void start(Stage stage) {
+        List<DecorationModel> decorationList = getDecorations();
+        Document document = new Document(text, decorationList, text.length());
+
+        RichTextArea editor = new RichTextArea();
+        editor.setDocument(document);
+
+        BorderPane root = new BorderPane(editor);
+
+        // decorate actions
+        ToggleButton fontBoldToggle = new ToggleButton("Bold");
+        new TextDecorateAction<>(editor, fontBoldToggle.selectedProperty().asObject(),
+                d -> d.getFontWeight() == BOLD,
+                (builder, a) -> builder.fontWeight(a ? BOLD : NORMAL).build());
+        ToggleButton fontItalicToggle = new ToggleButton("Italic");
+        new TextDecorateAction<>(editor, fontItalicToggle.selectedProperty().asObject(),
+                d -> d.getFontPosture() == ITALIC,
+                (builder, a) -> builder.fontPosture(a ? ITALIC : REGULAR).build());
+        ToggleButton fontUnderlinedToggle = new ToggleButton("Underline");
+        new TextDecorateAction<>(editor, fontUnderlinedToggle.selectedProperty().asObject(),
+                TextDecoration::isUnderline, (builder, a) -> builder.underline(a).build());
+        HBox actionsBox = new HBox(fontBoldToggle, fontItalicToggle, fontUnderlinedToggle);
+        actionsBox.getStyleClass().add("actions-box");
+        root.setTop(actionsBox);
+
+        Scene scene = new Scene(root, 800, 300);
+        scene.getStylesheets().add(ActionsDemo.class.getResource("actionsDemo.css").toExternalForm());
+        stage.setScene(scene);
+        stage.setTitle("RTA: Actions");
+        stage.show();
+
+        // select some text and change its decoration;
+        editor.getActionFactory().selectAndDecorate(new Selection(12, 27),
+                TextDecoration.builder().presets().fontFamily("Arial")
+                        .fontWeight(BOLD).underline(true)
+                        .build()).execute(new ActionEvent());
+    }
+
+    private List<DecorationModel> getDecorations() {
+        List<DecorationModel> decorations = new ArrayList<>();
+        // decoration for text
+        decorations.add(new DecorationModel(0, text.length(), preset, parPreset));
+        return decorations;
+    }
+
+}