Richtextfx: Write a Developer Guide

[JordanMartinez]

Coming from #356, which will complicate matters even more, we need to write a developer guide.

Last Updated: March 18, 2017
Most of the below tasks have been resolved in either the javadoc or in the Wiki

Master TODO List

• [x] Write a page that explains, or refers readers to pages that explain, RTFX's dependencies
• [x] Explain how to implement a custom style object
• [x] Explain how to implement a custom object in a paragraph's segment
• [x] Explain how to implement a custom SegmentOps
• [x] Explain how to implement a custom TextOps
• [ ] Write a page about how to use Codecs properly
• [ ] Determine a way to teach frequently-used API to new users

(original comment)
It should address the following issues:

• RTFX's CSS (already written via the CSS Ref Guide
• How to implement a custom Style object
• Gotchas, quirks, and other things to be aware of
• frequently-used API to help get a person started

[Jugen]

Undo/Redo Notes

The following three (3) conditions need to be met for undo/redo to work on custom segment objects:

1. The preserveStyle parameter must be TRUE when invoking the GenericStyledArea constructor.
2. A properly implemented Codec for your SEG must be set via GenericStyledArea.setStyleCodecs
3. The Object.equals( Object obj ) method must be overridden and properly implemented by your SEG

[JordanMartinez]

420 would probably help the "frequently-used API to help get a person started" part

[afester]

I have started to write down some of the stuff which I came across while implementing the custom object support at https://github.com/TomasMikula/RichTextFX/wiki/Developer-Guide-(Draft).
Would this be useful? We should probably also think about how to structure the developer guide (not sure if GitHub wiki supports sub pages - seems that all wiki pages are "global" to a project).
Any feedback is welcome ....

[JordanMartinez]

@afester Thanks for your initial work!

We should expand the last part in that draft: Implementing a custom style object.
Additionally, there should be a section that explains the proper way of implementing a GenericStyledArea with custom non-text style objects.

[JordanMartinez]

I wrote more of the implement a custom object guideline by extracting @afester's LinkedImage example into a code pattern for others to follow

[JordanMartinez]

I've included a page about implementing custom style objects in the guide.

[JordanMartinez]

I think the current SideBar in the Wiki should now replace the Home page on the Wiki.

[JordanMartinez]

I've replaced the Home page with the SideBar in the wiki while also including the link to the 3rd-party rich text editor comparison chart page.

I think we should also include a page that explains the dependencies of this project and how to get further information for them.

• For example, Val/Var/EventStream from ReactFX need to be understood to use this code in advanced ways. However, one who goes to the ReactFX page may not first read through the wiki. So, we should refer them to that.
• As for WellBehavedFX, we would simply point them to the override behavior demo link and the StyledTextAreaBehavior source code as examples.
• Flowless already has an explanation about its advantages and disadvantages, but to be consistent we should still rehash that in the "Dependencies of RichTextFX Explained" page.
• UndoFX has a pretty self-explanatory ReadMe, so we'd just need to link to that page and then explain how TextChange works as the change object

[JordanMartinez]

Additionally, we should add a comment about using Codecs properly. This would partly address the concern in #334.

[JordanMartinez]

The "Implement custom objects" wiki page needs to be updated due to #590

[Ansury]

Is this more for maintainer developers (people building from source or contributing) or user-developers? This sounds like it'd be useful but I don't see anything at the draft link above (I guess it's hidden?) I'll be willing to give feedback, if needed, once it's public.

I'm partially asking because I'm attempting to build from source, but it hasn't been as simple as a "gradle build" (on Linux). Still trying to determine if it's a local environment issue or not.

[afester]

it hasn't been as simple as a "gradle build" (on Linux).

It actually should - what are the error messages you get? Note that the build task also runs the integration tests - do NOT touch the mouse or the keyboard while those tests are running.

If that issue persists, please log a new Issue with the errors you are getting, so that we can continue the discussion there.

[JordanMartinez]

Is this more for maintainer developers (people building from source or contributing) or user-developers?

More for the developers who will be using this as a dependency in their projects (though some aspects are focused on contributors). Most of what we have so far is either written in the javadoc of the project (which is limited right now and needs to be updated) or in the wiki. I should also update the master list because it is somewhat outdated.

[JordanMartinez]

I'm partially asking because I'm attempting to build from source, but it hasn't been as simple as a "gradle build" (on Linux). Still trying to determine if it's a local environment issue or not.

I'm running Linux Mint with Java 8u141 and Gradle 4.2 and it works fine for me. Another person once had an issue with how the files were encoded, I think. I can't recall the exact issue of the top of my head.

[Ansury]

I'm using Linux Mint 18, Java 1.8.0_131, but gradle says it's 2.10. I'm also using Netbeans with a Gradle plugin. The funny thing is that it ran once (saw the tests running), but now it doesn't even get to that step. After I verify it isn't a local issue, I'll post an issue with what I'm seeing. (I wish Github had a project "forum" section where we could review incidents like this without creating issues which may or may not be legitimate!)

For the record, output from Gradle at this moment is showing these two lines over and over until it dies, so something looks very wrong:
at com.sun.tools.javac.comp.Resolve.isAccessible(Resolve.java:332)
at com.sun.tools.javac.comp.Resolve.isAccessible(Resolve.java:355)

Edit:
Ugh! OpenJDK doesn't include OpenJFX! That sucks. The reason it built correctly the first time is because I did it from NetBeans which is using a different JDK...

sudo apt install openjfx

It's a shame Gradle made finding that difficult, once I dumped the error output to a file I could actually see that it couldn't find the javafx packages... (sorry, just a old school Ant guy complaining about change).

[JordanMartinez]

:smile:
Is this issue closed then?

[afester]

Should we add a check for the proper JDK to the gradle build?

[JordanMartinez]

Should we add a check for the proper JDK to the gradle build?

Could you clarify what you mean? Are you talking about adding a gradle task will fail the build unless a specific JDK is used?

[JordanMartinez]

The only two tasks remaining in the master list are

1. Write a page about how to use Codecs properly
2. Determine a way to teach frequently-used API to new users

I think Codecs are in some way self-explanatory or are better explained in the javadoc. The frequently-used API is perhaps better resolved in the javadoc. So, for now, I'm closing this issue.

As for the JDK check, let's continue that discussion in a different issue.