Keyed rows under column headers, with selection and activation by key. More...

#include <backend.hpp>

Inheritance diagram for morph::ui::TableWidget:

Public Member Functions
virtual void	setColumns (std::vector< TableColumn > const &columns)=0
	Sets the column headers and widths.
virtual void	setShowHeader (bool shown)=0
	Sets whether the header row is drawn.
virtual void	setSelectionMode (SelectionMode mode)=0
	Sets how many rows the user can select.
virtual void	setRowKey (Widget &row, Key const &key)=0
	Tells the table which key a row stands for; called once per row, right after it is built. Marks the row when its key is requested.
virtual void	setRowTone (Widget &row, std::optional< Tone > tone)=0
	Sets a row's tone; called after setRowKey for a row given a tone, and on every change.
virtual void	setSelection (std::vector< Key > const &keys)=0
	Requests the rows with these keys, and marks those it has. Never calls the onSelectionChange handler.
virtual void	setOnSelectionChange (std::function< void(std::vector< Key >)> onSelectionChange)=0
	Sets what a user's selection change calls, with the keys of every row then selected.
virtual void	setOnActivate (std::function< void(Key)> onActivate)=0
	Sets what activating a row (Enter or a double click) calls, with its key.
virtual void	setRealizedWindow (std::size_t first, std::size_t count, std::size_t total)
	Tells the backend how many of the table's rows are realized, where, and how many exist in total, so it can size a scrollbar and place leading/trailing space for the rows that are not realized. A backend that never virtualizes (the default for every implementer but a windowed Qt Quick table) never calls setOnVisibleRangeChanged, so this is never called either.
virtual void	setOnVisibleRangeChanged (std::function< void(std::size_t, std::size_t)> onVisibleRangeChanged)
	Sets what the backend calls when the user scrolls, asking the mount to realize roughly this range of rows next. A backend that never virtualizes leaves this empty; the mount then never dewindows a row.
virtual void	setExistingKeys (std::vector< Key > const &keys)
	Tells the backend every key currently in the table's data, realized or not – called whenever that set changes (a data change, or a scroll that dewindows or re-realizes a row). A virtualized backend needs this to know a selected key still exists in the data when it has no realized row for it right now (setRowKey alone cannot say that, since it is only ever called for a realized row): without it, a backend that reconstructs "does this key still exist" purely from its realized children would silently drop a selected key's membership the moment its row scrolls out of view. A backend that never virtualizes may ignore this – every key it cares about already has a realized row, by definition, so setRowKey alone already tells it everything this call would add.
Public Member Functions inherited from morph::ui::ContainerWidget
virtual void	moveChild (Widget &child, std::size_t index)=0
	Moves `child` to position `index:` it is removed, then inserted before the child now at `index`.
Public Member Functions inherited from morph::ui::Widget
	Widget (Widget const &)=delete
Widget &	operator= (Widget const &)=delete
	Widget (Widget &&)=delete
Widget &	operator= (Widget &&)=delete
virtual void	setVisible (bool visible)=0
	Shows or hides the widget and everything inside it.
virtual void	setEnabled (bool enabled)=0
	Enables or disables input on the widget and everything inside it.
virtual void	setLayout (LayoutHints const &hints)=0
	Sets the size request.
virtual void	setDragKey (std::optional< Key > const &key)=0
	Makes the widget draggable, carrying `key`, or not draggable.
virtual void	setDropHandler (std::function< bool(Key const &)> accepts, std::function< void(Key)> onDrop)=0
	Makes the widget a drop target.
virtual void	setAccessibleName (std::string_view name)=0
	Sets the name assistive technology reads for the widget.
virtual void	setAccessibleRole (std::string_view role)=0
	Sets the role assistive technology announces for the widget.
virtual void	setTestId (std::string_view testId)=0
	Sets the stable identifier an automated test finds the widget by.
virtual void	setTooltip (std::string_view text)=0
	Sets the text shown while the pointer rests on the widget.
virtual void	setSurface (std::string_view surface)=0
	Styles the widget and everything inside it with a named token set of the theme.
virtual void	setKeys (std::vector< std::string > const &chords, std::function< void(std::string)> onChord)=0
	Declares the keyboard chords the widget handles while focus is inside it.
virtual void	focus ()=0
	Moves keyboard focus to the widget.
virtual void	setOnHover (std::function< void()> onHover)
	Calls `onHover` each time the pointer comes to rest over the widget. A backend without a pointer, or one that does not report hovering, keeps the default, which never calls it: hovering is a hint, such as a prefetch, never something a widget relies on.

Detailed Description

Keyed rows under column headers, with selection and activation by key.

Its children are the rows, each a horizontal stack whose children are the cells in column order. A hidden cell keeps its column: the cells after it stay under their own headers.

Selection is kept by key. The widget keeps the keys last requested by setSelection or selected by the user, and marks the current rows that have one of them: a key with no row marks nothing and stays requested, so a row that arrives with it later is marked, a row that goes is unmarked, and a reorder keeps the marks. Rows and selection may therefore arrive in either order. The selection mode limits what the user can select, not what setSelection marks.

A user's selection replaces the requested keys, and the widget shows it whether or not the application binds the selection. onSelectionChange then gets exactly the keys of the existing rows now selected, in any mode: a key still waiting for its row is dropped by a user's change, while setSelection keeps it waiting. It reports the user's selections only: no setter, and no row arriving or going, calls it.

Definition at line 462 of file backend.hpp.

Member Function Documentation

◆ setColumns()

virtual void morph::ui::TableWidget::setColumns ( std::vector< TableColumn > const & columns )

pure virtual

Sets the column headers and widths.

Parameters

columns The columns, in order.

Implemented in morph::ui::testing::detail::FakeTable.

◆ setShowHeader()

virtual void morph::ui::TableWidget::setShowHeader ( bool shown )

pure virtual

Sets whether the header row is drawn.

Parameters

shown false suits several tables sharing one visual header.

Implemented in morph::ui::testing::detail::FakeTable.

◆ setSelectionMode()

virtual void morph::ui::TableWidget::setSelectionMode ( SelectionMode mode )

pure virtual

Sets how many rows the user can select.

Parameters

mode	None, one, or any number.

Implemented in morph::ui::testing::detail::FakeTable.

◆ setRowKey()

virtual void morph::ui::TableWidget::setRowKey	(	Widget &	row,
		Key const &	key )

pure virtual

Tells the table which key a row stands for; called once per row, right after it is built. Marks the row when its key is requested.

Parameters

row	One of this table's rows.
key	The row's key.

Implemented in morph::ui::testing::detail::FakeTable.

◆ setRowTone()

virtual void morph::ui::TableWidget::setRowTone	(	Widget &	row,
		std::optional< Tone >	tone )

pure virtual

Sets a row's tone; called after setRowKey for a row given a tone, and on every change.

Parameters

row	One of this table's rows.
tone	The tone, or none.

Implemented in morph::ui::testing::detail::FakeTable.

◆ setSelection()

virtual void morph::ui::TableWidget::setSelection ( std::vector< Key > const & keys )

pure virtual

Requests the rows with these keys, and marks those it has. Never calls the onSelectionChange handler.

Parameters

keys	The selected keys.

Implemented in morph::ui::testing::detail::FakeTable.

◆ setOnSelectionChange()

virtual void morph::ui::TableWidget::setOnSelectionChange ( std::function< void(std::vector< Key >)> onSelectionChange )

pure virtual

Sets what a user's selection change calls, with the keys of every row then selected.

Parameters

onSelectionChange The handler; empty does nothing.

Implemented in morph::ui::testing::detail::FakeTable.

◆ setOnActivate()

virtual void morph::ui::TableWidget::setOnActivate ( std::function< void(Key)> onActivate )

pure virtual

Sets what activating a row (Enter or a double click) calls, with its key.

Parameters

onActivate The handler; empty does nothing.

Implemented in morph::ui::testing::detail::FakeTable.

◆ setRealizedWindow()

virtual void morph::ui::TableWidget::setRealizedWindow	(	std::size_t	first,
		std::size_t	count,
		std::size_t	total )

inlinevirtual

Tells the backend how many of the table's rows are realized, where, and how many exist in total, so it can size a scrollbar and place leading/trailing space for the rows that are not realized. A backend that never virtualizes (the default for every implementer but a windowed Qt Quick table) never calls setOnVisibleRangeChanged, so this is never called either.

Parameters

first	The view index of the first realized row.
count	How many rows are realized, starting at first.
total	How many rows the table's data has, realized or not.

Reimplemented in morph::ui::testing::detail::FakeTable.

Definition at line 506 of file backend.hpp.

◆ setOnVisibleRangeChanged()

virtual void morph::ui::TableWidget::setOnVisibleRangeChanged ( std::function< void(std::size_t, std::size_t)> onVisibleRangeChanged )

inlinevirtual

Sets what the backend calls when the user scrolls, asking the mount to realize roughly this range of rows next. A backend that never virtualizes leaves this empty; the mount then never dewindows a row.

Parameters

onVisibleRangeChanged The handler, with the first view index and how many rows are wanted from there; empty does nothing.

Reimplemented in morph::ui::testing::detail::FakeTable.

Definition at line 516 of file backend.hpp.

◆ setExistingKeys()

virtual void morph::ui::TableWidget::setExistingKeys ( std::vector< Key > const & keys )

inlinevirtual

Tells the backend every key currently in the table's data, realized or not – called whenever that set changes (a data change, or a scroll that dewindows or re-realizes a row). A virtualized backend needs this to know a selected key still exists in the data when it has no realized row for it right now (setRowKey alone cannot say that, since it is only ever called for a realized row): without it, a backend that reconstructs "does this key still exist" purely from its realized children would silently drop a selected key's membership the moment its row scrolls out of view. A backend that never virtualizes may ignore this – every key it cares about already has a realized row, by definition, so setRowKey alone already tells it everything this call would add.

Parameters

keys	Every key currently in the table's data, in no particular order.

Definition at line 529 of file backend.hpp.

The documentation for this class was generated from the following file:

morph/ui/backend.hpp

Public Member Functions

Detailed Description

Member Function Documentation

◆ setColumns()

◆ setShowHeader()

◆ setSelectionMode()

◆ setRowKey()

◆ setRowTone()

◆ setSelection()

◆ setOnSelectionChange()

◆ setOnActivate()

◆ setRealizedWindow()

◆ setOnVisibleRangeChanged()

◆ setExistingKeys()