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

• Write a page that explains, or refers readers to pages that explain, RTFX's dependencies
• Explain how to implement a custom style object
• Explain how to implement a custom object in a paragraph's segment
• Explain how to implement a custom SegmentOps
• 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.