This is ready for another look. The main changes are that SelectedContentController is now immutable (thinking of a new name for it), and selectable widgets are now identified through an optional selectableId. A user can request a new id through SelectableRegionState.nextSelectableId. While I'm not too fond of adding more selection parameters to Text, I think it will be difficult for the customer to map their widgets state to the selection without it.

edit: I plan to separate SelectionController into a separate PR

This is ready for another look. The main changes are that SelectedContentController is now immutable (thinking of a new name for it), and selectable widgets are now identified through an optional selectableId. A user can request a new id through SelectableRegionState.nextSelectableId. While I'm not too fond of adding more selection parameters to Text, I think it will be difficult for the customer to map their widgets state to the selection without it.

Friendly bump for review, changes today mainly include refactoring where the _TextSpanContentRange is created and the name change from SelectedContentController -> SelectedContentRange (open to suggestions on the name).

I also agree repurposing key is not a good idea. Can we force developer to provide the data model, ie textspan, that forms the selection subtree under the SelectionListener? It seems to me things starts to get weird if they are using SelectionListener without knowing the textspans in the subtree, and thus we try to use key to disambiguate them. However, should that be a valid use case?

If they have a subtree look like this.

Column(children: [TextA, UnKnownSelectable, TextB] )

Instead of wrapping a SelectionListener over entire column and try to disambiguate away the UnKnownSelectable, should they just do this instead

Column(children: [
  SelectionListener(
    dataModel: textSpan1,
    onChange: (){},
    builder: (data) => Text.rich(data)
  ),
  UnKnownSelectable,
  SelectionListener(
    dataModel: textSpan2, 
    onChange: (){},
    builder: (data) => Text.rich(data)
  )
])

I don't really know if this can solve your use case, but WDYT?

I don't have a strong opinion on using key as the identifier, I originally added a new parameter to Text called selectableId, but went the key route to avoid bloating the Text widget with more selection related fields and it seemed reasonable since the key is considered an identifier for the widget.

I do think we should consider including some identifier so the user does not have to use one particular method like multiple SelectionListeners and callbacks in the example, and can have the option to use a global SelectionListener and callback instead. I think the former adds overhead (especially with nested listeners and widgetspans) that we can provide a solution for with selectableId.

One issue I ran into when removing selectableId and updating the color selection red example is that it becomes difficult to know when to clear the selection. Let’s say the selection is spread across a column of 3 text widgets, if we clear the selection in the first text widgets listener then the operations we do in text widget 2 and 3 will not work since the selection will be cleared. This is because text 1 will receive the finalized selection first, do its logic and then clear the selection, not giving text 2 and text 3 a chance to do their logic. The onSelectionChanged from text 1 would need to know if text 2 and text 3 have a selection so it knows not to clear it. This can likely be done by saving the selectionDetails from text 2 and text 3. To me this seems like it adds more cognitive load to the user when compared to having one listener for a subtree, where they can clear the selection at the end of the onSelectionChanged callback.

I think the issue of when to clear the selection would also come up if we we force the developer to provide the data model like in @chunhtai example, since they still have to track all the selections from each listener.

column of 3 text widgets,

In this example you want to apply the same effect across 3 widgets (color selection red). In this case, you would wrap one selectionListener for all 3 widgets right?

Unless you have condition like widget 2 is some unknown stuff but still selectable and you want to disambiguate widget 2 out. Do you really have a use case like this? e.g. i only want to color the selection widget1 and widget 3 but not widget 2.

If you want to react to selection in a part of the screen, you have to know what's inside and thus you can just wrap one listener over the the widget subtree.

I may be missing some use cases, so I may be wrong here.

Yeah it would be preferable in the case of the color selection red example to wrap the entire subtree with one listener. I was mainly exploring using multiple to see how the usage of the API changed with multiple.

In the example of color selection red, let’s say part of the 3rd widget is selected. Then the user will only receive one SelectedContentRange. Is it reasonable to say that since the user is providing the data model to that subtree that they will know what part of their data model the offsets of the SelectedContentRange belong to? This sounds reasonable to me, though I think if we had the example with unselectable widgets interweaved it might get tricky. I think its also tricky because the offsets you will get in SelectedContentRange are relative to the text widget they came from. For example if we select some text in widget 3 and widget 3 is part of some overall data model, the offsets given will still be relative to widget 3 and not the data model.

Select 'text' in text widget 3:

dataModel = ['text widget 1', 'text widget 2', 'text widget 3'].

Text(dataModel[0])
Text(dataModel[1])
Text(dataModel[2])

returned ranges: [SelectedContentRange(start: 0, end: 4, contentLength: 13)].

I'm not sure in the example above how the user would know where the range came from, and how to update their data model accordingly.

Let’s say the selection is spread across a column of 3 text widgets, if we clear the selection in the first text widgets listener then the operations we do in text widget 2 and 3 will not work since the selection will be cleared. This is because text 1 will receive the finalized selection first, do its logic and then clear the selection, not giving text 2 and text 3 a chance to do their logic. The onSelectionChanged from text 1 would need to know if text 2 and text 3 have a selection so it knows not to clear it. This can likely be done by saving the selectionDetails from text 2 and text 3. To me this seems like it adds more cognitive load to the user when compared to having one listener for a subtree, where they can clear the sele...

That's the case we talked about yesterday right? My thought was that in this case you need an API that query the current SelectionDetails from each segment (by that I mean each listener) so you can find out the SelectionDetails when the user clicks the "paint me red" button, instead of the ability of listening for SelectionDetails changes in each segment. But now that I think about it, if you want to implement a listener api, wouldn't you need the ability to query the current SelectionDetails anyway? The moment the user starts subscribing to the SelectionDetails of a selection listener, they should get an event that represents the current SelectionDetails (or at least there has to be a way to ask for it). Think of it as a ValueNotifier<SelectionDetails>, if the user subscribes to such a ValueNotifier, they should be able to extract the value, or they will have to wait for the first time the value changes after the subscription.

Is the pseudocode below kind of what you're pointing at @LongCatIsLooong?

onPressed: () {
    final SelectionDetails? selectionText1 = selectionListener1.value;
    final SelectionDetails? selectionText2 = selectionListener2.value;
    final SelectionDetails? selectionText3 = selectionListener3.value.
    if (selectionText1 != null) {
        _colorRed(index: 0, selectionText1.ranges);
    }
    if (selectionText2 != null) {
        _colorRed(index: 1, selectionText2.ranges);
    }
    if (selectionText3 != null) {
        _colorRed(index: 2, selectionText3.ranges);
    }
    _clearSelection();
}

I think this works when using multiple listeners, but am not sure how a user would know if the selection is finalized with this approach. Maybe we can have a SelectionListener.onSelectionFinalized callback, but that seems a little tricky since a user would have to know if the selection has been finalized / is ongoing in SelectionListeners adjacent to it.

In the color red example, where it makes more sense to use one listener to wrap the entire subtree, I think we still run into the issue where a user won't know where the selection came from, using the query approach.

I think this works when using multiple listeners, but am not sure how a user would know if the selection is finalized with this approach

Do you mean if the user is dragging to expand the selection and at the same time the onPressed callback is invoked, the callback should wait for the next finalize event? That doesn't seem a common thing to do. Or if the user just wants the next finalized event, they can just return early in the listener callback if details.isFinalized is false?

Yeah they could wait for the next finalized event before showing the context menu. I wasn't sure with the query approach where exactly they would listen to that finalized event, but the user can wrap the subtree they're listening to with another SelectionListener and check if the selection is finalized that way and then trigger the context menu. Or they can make another SelectionContainer that just listens for the finalized event themselves.

I added variants of both examples with/without selectableId. Curious to hear any thoughts regarding pros and cons of either approach.

IMO having no selectableId adds another layer of management that the user has to worry about since they now have to track each SelectionDetails coming from every listener. Also having to wrap every Text widget with a SelectionListener looks a little verbose to me, especially for simpler cases like the color selection red example, where it might make more sense to just wrap the subtree of 3 text widgets with a single SelectionListener. A querying approach would also run into the same verbosity I think since we would still have to wrap each individual widget with a listener.

I think adding selectionId is probably ok, though I think we should figure out a way to

1. not drill it down from widget like Text(), we can consider a composition approach like a wrapper widget
2. if we do 1, we may need a way to declare relation between datamodel and selectionId.

As of using multiple Listener vs one. I don't really know, I guess we will only figure out when we have more use case.

Yeah they could wait for the next finalized event before showing the context menu. I wasn't sure with the query approach where exactly they would listen to that finalized event, but the user can wrap the subtree they're listening to with another SelectionListener and check if the selection is finalized that way and then trigger the context menu. Or they can make another SelectionContainer that just listens for the finalized event themselves.

For cases of multipleListener couldn't the isFinalized boolean to be include in the onSelectionChange callback?

I also think there are a lot of different approach that target different use case are proposed here. I think which ever solution we choose should be flexible enough to be able to build on top later.

For example, the decision may be that we don't necessary selectionId for now, but we should keep in mind we may need it in the future. so the implementation should not write us into a dead end