High performance text component

[Richard Bair]

Actually, it is a *lot* simpler than you fear. (brought the subject back). It isn't a DOM in the HTML sense, but more in the generic sense, I guess the name in the WIKI title is confusing. 

When we say DOM, we mean in the generic sense of some object model that represents your text. The alternative is the programmatic attributed string approach, where you have a StringBuffer type object and you tell it which ranges of characters have which attributes. The DOM approach instead uses the Scene Graph as the document object model.

Just to be abundantly clear, we're NOT talking about the HTML DOM in any of this. That document object model has a whole lot of subtle differences such as event handling etc, and there is no way we're going down that road. SO when Felipe says "DOM API", what he means is, we're using the Scene Graph to model the text, and not an AttributedString style API.

Felipe, we should update the documents on the WIKI to refer to the "Rich Text API" instead of DOM API because I fear this can get confusing! Other than those of us internally who have argued for / against the Attributed String style vs. the DOM style, most people probably won't get the subtlety, having missed the context.

> First reaction is why do we have two things a "Scene Graph" and a "DOM", why not just one. Also "laying out" will inevitably creep in here for 'rich text' if you go down this road (see 'overflow: hidden' comment below, what's next, 'padding', 'height', or shudder 'position', 'float', etc). 

There is only the SceneGraph. Everything is in the scene graph. My current favorite as far as the proposal is to introduce 1 new node class, lets call it Paragraph. It is like a DIV in HTML (but not a DIV, hence a different name), and it contains all Text nodes, and can handle any other type of node you throw in there.

So for example, I'm taking Sample 1 from Felipe's Samples WIKI https://wikis.oracle.com/display/OpenJDK/DOM+API+Samples, but modifying it for my current feelings on the naming and such (since we have to pick something, and for the sake of this I want to avoid DIV / SPAN since that has specific HTML connotations).

@Override
public void start(Stage stage) throws Exception {
    String family = "Helvetica";
    double size = 20;
     
    Paragraph p = new Paragraph(40, 40);
    Text hello = new Text("Hello ");
    hello.setFont(Font.font(family, size));
    Text bold = new Text("Bold");
    bold.setFont(Font.font(family, FontWeight.BOLD, size));
    Text world = new Text(" World");
    world.setFont(Font.font(family, FontPosture.ITALIC, size));
    p.getChildren().addAll(hello, bold world);
     
    Group group = new Group(p);
    Scene scene = new Scene(group, 500, 500, Color.WHITE);
    stage.setTitle("Hello Rich Text");
    stage.setScene(scene);
    stage.show();
}

So as you can see, the "document object model" here is just the scene graph (there are many DOMs in the world, Bilbo, and none of them should be used lightly!).

The Paragraph node is just a very specialized layout container, which knows how to layout text nodes properly. Felipe, can you add a sample of complex text and show how that works? That really motivates the complex scenario that cannot just be handled by a FlowPane with text nodes. Another case is where you break at the word boundary for line breaking, but the word being broken is in a Text node (such that part of the Text node is on one line, and part of it on the next). All flowing and working with complex text. That's the work of the Paragraph node and why we need an additional node beyond FlowPane.

I can definitely see in the future people wanting to add more web layout functionality (flowing text around an Image, for example). We will have, for example, padding and borders and such by virtue of using Region (which supports these things). I would be cautious about adding overflow controls and such, although it is certainly possible, it would require us adding a new NGParagraph node type so that we could handle it without modifying the scene graph (the user might have their own clip on Paragraph, and so we cannot set the clip on the Paragraph itself but would have to handle it further down), and I certainly wouldn't want Paragraph to require a ScrollPane (breaks our modularity).

And although I feel that at some point in the future we will inevitably be drawn into more complex layout support (flowing text around Image!), it doesn't have to go that way and certainly by choosing names other than Div and Span we can emphasize this is something different.

> Your comment: 
> > which might make sense in some document heavy scenarios
> 
> A webapp (even the richest of rich) is a 'document heavy scenario', i.e. all things can be seen in this category, where's the line (lessons from the web would say there isn't one).

That is true, although I think that is also why people who hate programming for the web hate it so much -- it tries to see the entire world through the lens of a document, when really that only covers some of the use cases. But in our world, you can put a full TabPane or other layout container in the Paragraph, or vice versa, as your mood or fancy or use case requires. But really Paragraph exists not for laying out the entire application, but for rich text scenarios. Word allows you to embed graphs and tables, we need to allow for the same.

> I think I need to digest a little more though, this feels like a fundamental change in the way things could/should be done. 

I don't think so, I think some people might prefer the document approach and go crazy with it, but I expect for the most part Paragraph and Text are used for rich text scenarios, including scenarios where you are embedding images and such in the rich text.

Cheers
Richard