Design: Support checkboxes in Tables and Trees

[corranwebster]

What is the problem or limitation you are having?

Displaying a checkbox is a simple way of indicating a true/false value for a row in a Table or Tree. Occasionally a third, indeterminate, value may be called for (eg. in a Tree when some children are checked and some are not).

Currently only the MacOS backend supports displaying checkboxes in a table via using a Switch widget as the cell value. Other backends can fake the effect by using an icon which looks like a checkbox or other icon-style indicator. However all the other backends have support for checkboxes in columns in various ways.

Initially just being able to display a checkbox would be good, but having the option of making them user-editable would potentially be even better, and because they are simple true/false in most cases, it may provide a simpler case to explore adding editability to tables and trees.

Describe the solution you'd like

With #4041 being merged, this should be somewhat easier to implement support. Initially the behaviour we want should be something like:

• if the row value obtained via the accessor is a bool, then rather than displaying "True" or "False", the table or tree should display a checkbox which is checked if True and unchecked if False.
• (possibly) we introduce a third value Indeterminate which shows an indeterminate checkbox
• (possibly, but unlikely) if the value is a Switch widget, display a checkbox whose value matches the value of the switch (this will be awkward to keep synchronised if editing is allowed).
• (possibly) if a cell holds a tuple (icon, text, ..., checked, ...) then in addition to the icon and text, it should display a checkbox whose state is checked. Exactly which position the checked value should take is unclear, since there are other values we may want to put in there; for example having the third item be a detail or tooltip text would be more compatible with DetailedList, and we may want a place for style information to be provided as well (or not).
• otherwise no checkbox is displayed.

This is technically not backwards compatible, but not in a way that breaks things terribly.

To support checking/unchecking behaviour, the data source needs to provide row objects such that setattr(row, accessor, value) works and performs an appropriate change notification from the source, and possibly the table should have a global editable setting which can be set true or false. When the user changes the state of the checkbox, the table should set the new value. Code which cares about changes to the checkboxes can listen to the data source for changes and react appropriately.

For backwards compatibility, a table being editable should be opt-in.

Describe alternatives you've considered

Instead of doing this, it might be that complete generic Widget support as in the current MacOS backend is better and is what each backend should strive for.

Additional context

This can be implemented by the ColumnT protocol growing a checked method, and having the AccessorColumn implementation handle the logic above. If column objects are exposed as a public API, different implementations could provide the data for the checked column in different ways.

Editability of checkmarks could similarly be via the protocol growing checkable(row), set_value(row, value) and set_checked(row, checked) methods (or other equivalent names): checkable returns a True/False if the user should be able to change the check value in this row and column, set_value handles setting the value into the row object, and set_checked handles any conversion that's needed to get the value formatted to match the existing value (eg. if given an (icon, text, ..., checked, ...) value, set the value back to a tuple of the same format but with the checked value changed.)

There should be a widget-wide editable/not-editable flag which is false by default.

Editability also requires that whatever the row objects are, they should emit a change notification for the row when the value is set. In the current implementations that means that the AccessorColumn should be simply doing setattr(row, accessor, value) and the row objects need to be able to have attributes set on them, and should make the source emit change notifications (which the default Row and Node objects do, but custom ones would need to implement).

Other editability could then grow from this base (eg. editable text re-using set_value).

[freakboy3742]

Agreed that a checkbox is a common use case here; and the API you've suggested here generally makes sense to me.

However, it's not the only use case - there's also text entry, numeric entry, etc. To that end, I'd be hesitant to add specific handling for a single widget type, no matter how common that use case is.

The current widget handling in Table is very closely tied to how macOS implements tables; it's been a while since I've looked at this, but my recollection is that the "arbitrary widget in a cell" approach is going to be difficult to accomodate on other platforms. It's also interesting to note that macOS tables have native "text value editing" handling which we have to explicitly disable. So even there, "widget in a table" is the wrong metaphor.

The good news is that I don't think we don't actually need full "arbitrary widget in a cell" functionality. There's a limit to the types of widgets that would ever be realistic to put in a table (honestly - checkbox and text entry would likely solve most of them).

So - instead of adding explicit checked handling, I'd prefer to add a higher level interface that can be implemented in multiple ways - "checked" being an obvious first candidate, but "editable text" would be another.

I'd also be hesitant adding a new API in this space without it being informed by what is actually possible on macOS, GTK, Qt and Windows. We've already got one platform-specific API; I'd rather not add a new one that can't be implemented on one or more platforms. I'm less concerned about Android and iOS; neither have a Tree right now, and Android's table is a stop-gap mechanism; and the designs I've got floating around in my head for "end game" Table and Tree on mobile would involve more straightforward "form" type handling that should be fairly accomodating.

[corranwebster]

However, it's not the only use case - there's also text entry, numeric entry, etc. To that end, I'd be hesitant to add specific handling for a single widget type, no matter how common that use case is.

The reason I proposed it this way is because checkbox + text or checkbox + icon + text is a common pattern even without editing, and editable text plus edit editable checkbox is also used, so I'm not thinking of the checkbox as the value being edited, but a value that can be edited. But it might be enough to just have one of them and if you need a checkbox and editable text, then you have two columns.

I'd also be hesitant adding a new API in this space without it being informed by what is actually possible on macOS, GTK, Qt and Windows. We've already got one platform-specific API; I'd rather not add a new one that can't be implemented on one or more platforms. I'm less concerned about Android and iOS; neither have a Tree right now, and Android's table is a stop-gap mechanism; and the designs I've got floating around in my head for "end game" Table and Tree on mobile would involve more straightforward "form" type handling that should be fairly accomodating.

I had a quick check of capabilities before writing this:

• Gtk allows you to pack multiple renderers into a cell, so you can have an icon, a checkbox and text in the same cell, and it looks like both the checkbox and text can be editable independently (ie. one or the other or both).
• Qt models can provide icon, checkbox and text data (amongst others), as well as flags that allow text editability and checking independently.
• Winforms is limited to checkboxes in the first column (same as icons). It can handle both checkbox click and text editing events in that column. This would also be the case for a Winforms Tree, if implemented, I think. If we used a GridView instead of a ListView for tables you'd need a custom column type for icons and text, so it wouldn't be a big lift to add a checkbox to that, but GridView doesn't support that out of the box.
• MacOS seems to also allow checkboxes and editable text in the same cell, and have them editable or not independently, but I think via essentially having multiple widgets in the cell.

So Winforms is the odd-one-out, but in a way that it's already different.

More generally for editors inside cells:

• Gtk has a set of pre-defined renderers for common editors (text, image, checkbox, combobox, number spin box, progress bar, etc.) that likely cover most use cases. Multiple renderers can be packed into a cell, and we are already doing this for icon + text.
• Qt gives you icon, checkbox and editable text out of the box. For other editors you need to define a delegate that overrides createEditor and methods to get and set the data inside that, but then you can return any widget you want.
• MacOS allows arbitrary widgets inside cells.
• Winforms ListView and TableView are text-editor only other than a checkbox in the first column, it seems, GridView allows you to define columns which can hold anything you want, along with standard column types which provide a single-field editor. So it's easy to get a combobox, but much more work to get an icon and a combobox in the same cell, for example.

And for completeness:

• Textual data tables are read-only (you can select, but not edit)
• Web should be able to contain anything you want in a cell, I think.

So I think the question more generally is does a cell have a single "editor", or do we want a format like:

+------------------------+
| [x] <icon> Text/Editor |
+------------------------+

within each cell?

[freakboy3742]

Thanks for that background research - that's all very helpful.

Broadly, it looks like almost anything is on the table, except on Textual, and on Winforms unless we move to a DataGridView-based implementation. There will be varying degrees of "custom widget layout" for a cell; but most of the backends seem to accomodate that in one form or another.

So I think the question more generally is does a cell have a single "editor", or do we want a format like:

+------------------------+
| [x] <icon> Text/Editor |
+------------------------+

within each cell?

I'm wary of hard-coding too much in layout. If a cell contains just an icon, or just text, or just a widget, then it's clear how that will be displayed.

If we allow for "checkbox, icon, text" - then there's 6 possible orderings that could be presented to the user (12 if you allow for 2-tuples as well). Whichever one we pick, someone is going to want a different one.

We do currently have "icon, text" as an option; LTR language defaults gives us a little coverage there. If we add checkboxes into the mix as well, then we have to litigate if it makes more sense for the checkbox to go to the left or the right of the icon, etc.

I'm also wary of adding support for a checkbox independent of generic cell editing. Is there a use case for a checkbox on a row that isn't displaying or editing an attribute of that row?

I don't think the full "widget" setup that macOS support is correct - that seems very heavyweight, unless we're going down the path of providing complete configurability over cell contents. However, that seems like overkill for the vast majority of cases.

To me, it feels like a public Column class needs to expose some sort of interface for defining the order of cell contents for that column, and the connection back to the Source for setting data. That could be as simple as a tuple defining (Column.ICON, Column.VALUE) (or similar); "widgets" then become symbolic values you can put in that tuple, rather than fully fledged Widget instances.

[corranwebster]

I'm also wary of adding support for a checkbox independent of generic cell editing. Is there a use case for a checkbox on a row that isn't displaying or editing an attribute of that row?

In implementation, I think we have to go through attributes of a row object because that's the way that the tables work.

But in terms of intent, checkboxes are often used to provide multiple selection from a table or tree where everything else is fixed and non-editable: what's being edited isn't so much the underlying data, but the set of rows which is being chosen. This sort of thing:

But maybe that's a different widget built on top of a source than the table or tree, just like the Selection widget is a different widget built on top of a source, since in this case what's being edited is the set of chosen items, not the data source.

[freakboy3742]

Hrm - I'm not sure if it's a different widget, or a different source. If you take your screenshot of a file tree as an example - this might be a "which files do we want to run Black on?"; which is more of a permanent stored property, rather than a selection.

I guess it depends on whether you consider the "selection" in this case to be a widget visualisation thing, or an "underlying representation" thing. And if it is a widget visualisation thing - how does it distinguish itself from "multiple selection" as existing functionality.

Having it in the source is only a problem if you have multiple widgets viewing the source... but as other threads have determined, that's more of an edge case than the common case; and even then, it seems just as likely that a checkbox like that is something that would be shared. A proxied source could add a checkbox attribute to a row without much difficult as well.