Skip to content

Commit f70b978

Browse files
JordanMartinezJordanMartinez
committed
Update ReadMe
- Clarify scope and additional features - Revise explanation of the flavors of areas and their usage - Fix broken demo screenshot link issues
1 parent 80c9e7f commit f70b978

1 file changed

Lines changed: 45 additions & 53 deletions

File tree

‎README.md‎

Lines changed: 45 additions & 53 deletions
Original file line numberDiff line numberDiff line change
@@ -1,15 +1,22 @@
11
RichTextFX
22
==========
33

4-
RichTextFX provides a text area for JavaFX with API to style ranges of text. It is intended as a base for rich-text editors and code editors with syntax highlighting.
4+
RichTextFX provides a memory-efficient text area for JavaFX that allows the developer to style ranges of text, display custom objects in-line (no more HTMLEditor), and override the default behavior only where necessary without overriding any other part of the behavior.
5+
6+
It does not follow the MVC paradigm as this prevented access to view-specific API (e.g., getting the bounds of the caret/selection/characters, scrolling by some amount, .
7+
8+
It is intended as a base for rich-text editors and code editors with syntax highlighting. Since it is a base, a number of suggested features (specific syntax highlighters, search-and-replace, specific support for hyperlinks, etc.) will not be implemented directly in this project. Rather, developers can implement these on top of RichTextFX and submit their work as a PR to the `richtextfx-demos` package.
9+
10+
For a greater explanation of RichTextFX, its design principles, how it works, and how to style its areas via CSS, please [see the wiki](https://github.com/TomasMikula/RichTextFX/wiki)
511

612
* [Who uses RichTextFX?](#who-uses-richtextfx)
713
* [Features](#features)
814
* [Flavors](#flavors)
9-
* [StyleClassedTextArea](#styleclassedtextarea)
10-
* [CodeArea](#codearea)
11-
* [InlineCssTextArea](#inlinecsstextarea)
12-
* [InlineStyleTextArea](#inlinestyletextarea)
15+
* [GenericStyledArea (Base area class requiring customization)](#genericstyledarea)
16+
* [StyledTextArea (Areas ready out-of-box)](#styledtextarea)
17+
* [InlineCssTextArea](#inlinecsstextarea)
18+
* [StyleClassedTextArea](#styleclassedtextarea)
19+
* [CodeArea (Base for code editors)](#codearea)
1320
* [Requirements](#requirements)
1421
* [Demos](#demos)
1522
* [Highlighting of Java keywords](#automatic-highlighting-of-java-keywords)
@@ -45,88 +52,73 @@ If you use RichTextFX in an interesting project, I would like to know!
4552
Features
4653
--------
4754

48-
* Assign arbitrary styles to arbitrary ranges of text.
55+
* Assign arbitrary styles to arbitrary ranges of text. A style can be an object, a CSS string, or a style class string.
4956
* Display line numbers or, more generally, any graphic in front of each paragraph. Can be used to show breakpoint toggles on each line of code.
57+
* Support for displaying other `Node`s in-line
5058
* Positioning a popup window relative to the caret or selection. Useful e.g. to position an autocompletion box.
5159
* Getting the character index under the mouse when the mouse stays still over the text for a specified period of time. Useful for displaying tooltips depending on the word under the mouse.
60+
* Overriding the default behavior only where necessary without overriding any other part.
5261

5362

5463
Flavors
5564
-------
5665

57-
### StyleClassedTextArea
66+
The following explains the different rich text area classes. The first one is the base class from which all others extend: it needs further customization before it can be used but provides all aspects of the project's features. The later ones extend this base class in various ways to provide out-of-box functionality for specific use cases. **Most will use one of these subclasses.**
5867

59-
`StyleClassedTextArea` lets you assign style classes to ranges of text. You can define the style classes in your stylesheet.
68+
### GenericStyledArea
6069

61-
Example.java:
70+
`GenericStyledArea` allows one to inline custom objects into the area alongside of text. As such, it uses generics and functional programming to accomplish this task in a completely type-safe way.
6271

63-
```java
64-
area.setStyleClass(from, to, "red");
65-
```
72+
It has three parameter types:
73+
- `PS`, the paragraph style. This can be used for text alignment or setting the background color for the entire paragraph. A paragraph is either one line when text wrap is off or a long text displayed over multiple lines in a narrow viewport when text wrap is on,
74+
- `SEG`, the segment object. This specifies what immutable object to store in the model part of the area: text, hyperlinks, images, emojis, or any combination thereof.
75+
- `S`, the segment style. This can be used for text and object styling. Usually, this will be a CSS style or CSS style class.
6676

67-
example.css:
77+
Functional programming via lambdas specify how to apply styles, how to create a `Node` for a given segment, and how to operate on a given segment (e.g., getting its length, combining it with another segment, etc.).
6878

69-
```css
70-
.red { -fx-fill: red; }
71-
```
79+
`GenericStyledArea` is used in the [Rich-text demo](#rich-text-editor) below.
7280

73-
This renders the text in the range `[from, to)` in red.
81+
See the wiki for a basic pattern that one must follow to implement custom objects correctly.
7482

75-
Note that the style classes are assigned to instances of [Text](http://download.java.net/jdk8/jfxdocs/javafx/scene/text/Text.html), so you can specify any [CSS properties applicable to a Text node](http://docs.oracle.com/javafx/2/api/javafx/scene/doc-files/cssref.html#text).
83+
### StyledTextArea
7684

77-
#### CodeArea
85+
`StyledTextArea<PS, S>`, or one of its subclasses below, is the area you will most likely use if you don't need to display custom objects in your area.
7886

79-
`CodeArea` is a variant of `StyleClassedTextArea` that uses a fixed width font by default, making it a convenient base for source code editors. `CodeArea` is used in the [Java Keywords demo](#automatic-highlighting-of-java-keywords) below.
87+
It extends `GenericStyledArea<PS, StyledText<S>, S>>`. `StyledText` is simply a text (`String`) and a style object (`S`). A slightly-enhanced [JavaFX `Text`](https://docs.oracle.com/javase/8/javafx/api/javafx/scene/text/Text.html) node is used to display the `StyledText<S>`, so you can style it using [its CSS properties](https://docs.oracle.com/javase/8/javafx/api/javafx/scene/doc-files/cssref.html#text) and additional RichTextFX-specific CSS (see the wiki for more details).
88+
89+
It properly handles the aforementioned functional programming to properly display and operate on `StyledText<S>` objects.
8090

91+
The style object (`S`) can either be a CSS String (`-fx-fill: red;`), a CSS styleclass (`.red { -fx-fill: red; }`), or an object that handles this in a different way. Since most will use either the CSS String or CSS style class approach, there are two subclasses that already handle this correctly.
8192

8293
### InlineCssTextArea
8394

84-
`InlineCssTextArea` lets you specify inline CSS for a range of text.
95+
`InlineCssTextArea` uses the `Node#setStyle(String cssStyle)` method to style `Text` objects:
8596

8697
```java
8798
area.setStyle(from, to, "-fx-font-weight: bold;");
8899
```
89100

90-
Again, you can use any CSS properties applicable to a `Text` node.
91-
92-
93-
### InlineStyleTextArea
101+
### StyleClassedTextArea
94102

95-
`InlineStyleTextArea<S>` is a more general version of `InlineCssTextArea`. In the end, there is still inline CSS assigned to `Text` nodes, but instead of using the CSS string directly, you use an instance of your custom style representation `S` and provide a way (function) to convert `S` to CSS string in `InlineStyleTextArea` constructor.
103+
`StyleClassedTextArea` uses the `Node#setStyleClass(String styleClass) method to style `Text` objects. You can define the style classes in your stylesheet.
96104

97-
```java
98-
class MyStyleInfo {
99-
boolean bold;
100-
boolean italic;
101-
102-
String toCss() {
103-
return "-fx-font-weight: " + (bold ? "bold" : "normal") + ";"
104-
+ "-fx-font-style: " + (italic ? "italic" : "normal") + ";";
105-
}
106-
}
105+
example.css:
107106

108-
InlineStyleTextArea<MyStyleInfo> area =
109-
new InlineStyleTextArea<>(new MyStyleInfo(), styleInfo -> styleInfo.toCss());
107+
```css
108+
.red { -fx-fill: red; }
110109
```
111110

112-
The first constructor argument is the default style to use for ranges of text where you don't set the style explicitly. The second constructor argument is the function to convert the custom style representation to CSS.
113-
114-
You then assign an instance of your custom style representation to a range of text.
111+
Example.java:
115112

116113
```java
117-
MyStyleInfo styleInfo = ...;
118-
119-
area.setStyle(from, to, styleInfo);
114+
area.setStyleClass(from, to, "red");
120115
```
121116

122-
You appreciate the benefits of this approach over `InlineCssTextArea` when you need to query the style used at a given position in text - you get back an instance of your style representation instead of a CSS string.
123-
124-
```java
125-
MyStyleInfo styleInfo = area.getStyleAt(charIndex);
126-
```
117+
This renders the text in the range `[from, to)` in red.
127118

128-
`InlineStyleTextArea` is used in the [Rich-text demo](#rich-text-editor) below.
119+
#### CodeArea
129120

121+
`CodeArea` is a variant of `StyleClassedTextArea` that uses a fixed width font by default, making it a convenient base for source code editors. `CodeArea` is used in the [Java Keywords demo](#automatic-highlighting-of-java-keywords) below.
130122

131123
Requirements
132124
------------
@@ -141,7 +133,7 @@ Demos
141133

142134
### Automatic highlighting of Java keywords
143135

144-
![Screenshot of the JavaKeywords demo](https://googledrive.com/host/0B4a5AnNnZhkbYlVlbVprYnhPdVk/java-keywords.png)
136+
![Screenshot of the JavaKeywords demo](https://cloud.githubusercontent.com/assets/8413037/24158979/1ef7af14-0e1b-11e7-8c06-69cb9e5a2dd7.png)
145137

146138
#### Run using the pre-built JAR
147139

@@ -191,7 +183,7 @@ Similar to the [Java Keywords](#automatic-highlighting-of-java-keywords) demo ab
191183

192184
### Rich-text editor
193185

194-
![Screenshot of the RichText demo](https://googledrive.com/host/0B4a5AnNnZhkbYlVlbVprYnhPdVk/rich-text.png)
186+
![Screenshot of the RichText demo](https://cloud.githubusercontent.com/assets/8413037/24158984/22d36a10-0e1b-11e7-95e0-f4546cb528c3.png)
195187

196188
#### Run using the pre-built JAR
197189
[Download](https://github.com/TomasMikula/RichTextFX/releases/download/v0.6.10/richtextfx-demos-fat-0.6.10.jar) the pre-built "fat" JAR file and run
@@ -211,7 +203,7 @@ Similar to the [Java Keywords](#automatic-highlighting-of-java-keywords) demo ab
211203

212204
When the mouse pauses over the text area, you can get index of the character under the mouse. This allows you to implement, for example, custom tooltips whose content depends on the text under the mouse.
213205

214-
![Screenshot of the RichText demo](https://googledrive.com/host/0B4a5AnNnZhkbYlVlbVprYnhPdVk/tooltip-demo.png)
206+
![Screenshot of the RichText demo](https://cloud.githubusercontent.com/assets/8413037/24158992/2741225e-0e1b-11e7-9d6b-6040dc30cee1.png)
215207

216208
#### Run using the pre-built JAR
217209
[Download](https://github.com/TomasMikula/RichTextFX/releases/download/v0.6.10/richtextfx-demos-fat-0.6.10.jar) the pre-built "fat" JAR file and run

0 commit comments

Comments
 (0)
⚡