ClaFi Grid

Introduction

The structure you see in that picture — different column levels, visual cell spans and merges, groups — falls out of two hierarchies, a tree of columns and a tree of rows, plus one fact per cell: whether that row fills that column.

You describe all of it — columns, rows, and the contents of every cell — as a single nested declaration:

Grid& m_grid{ add<Grid>(
    Columns{ /* the column tree */ },
    Header{}, // The grid header is optional, this line creates one
    Rows{ /* the rows, and the cells in them */ }
) };

The grid builds itself from that list and, for each row, connects a pair of handlers to that row: one answering which columns the row fills, one supplying the text of its cells. The grid asks the row while it lays out, paints and hit-tests, so there is no second place to keep in sync. The row owns those connections, so nothing outside the grid has to stay alive.

Quick Start

A grid with two columns and two rows. This is the whole thing:

import ClaFi.Controls.Grids_Dt;
import ClaFi.Controls.Grids;
import ClaFi.Controls.Stack;
import ClaFi.Core.TextEngine.Text;
import ClaFi.Core.Foundation;
import ClaFi.Core.System.UiTypes;

namespace MyApp
{
    using namespace ::ClaFi;
    using namespace ::ClaFi::Controls;
    using namespace ::ClaFi::Controls::Grids::Dt;

    enum class Col
    {
        Name,
        Size
    };

    class FilesPage : public Stack
    {
    public:
        explicit FilesPage(const CreateParams&);
    private:
        Grid& m_grid{ add<Grid>(
            Columns{
                Column{ Tag{ Col::Name }, Text{ L"Name" } },
                Column{ Tag{ Col::Size }, Text{ L"Size" } }
            },
            Header{},
            Rows{
                Row{
                    Cell{ Tag{ Col::Name }, [](Grids::GetCellTextEvent& event) {
                        event.text() << L"readme.txt";
                    } },
                    Cell{ Tag{ Col::Size }, [](Grids::GetCellTextEvent& event) {
                        event.text() << L"1.2 KB";
                    } }
                },
                Row{
                    Cell{ Tag{ Col::Name }, [](Grids::GetCellTextEvent& event) {
                        event.text() << L"notes.md";
                    } },
                    Cell{ Tag{ Col::Size }, [](Grids::GetCellTextEvent& event) {
                        event.text() << L"640 B";
                    } }
                }
            }
        ) };
    };

    FilesPage::FilesPage(const CreateParams& params)
        :
        Stack{ params, Orientation::Vertical }
    {
    }
}

namespace MyApp
{
    using namespace ::ClaFi;
    using namespace ::ClaFi::Controls;
    using namespace ::ClaFi::Controls::Grids::Dt;

Four things to notice, because they apply everywhere:

• The Grid builds itself from its argument list in its constructor. Anything that list names - a CellSet, a member a row reads - has to be declared before the grid, because members are built in declaration order.
• A column is named by its Tag — an ordinary property, forwarded to the column like any other. Any enum or integer works. The values have to be unique among the columns of one grid, and a debug build says so if they are not.
• A cell names its column with that same Tag — Cell{ Tag{ Col::Name }, ... }.
• A row has cells only where you give it cells. A row with no cell in Col::Size has no cell there at all — not an empty one.

Text usually comes from your data rather than a literal. Point the cell at a member function and it will be called whenever that cell needs drawing:

void FilesPage::nameCell(Grids::GetCellTextEvent& event) const
{
    event.text() << m_files[event.row().tag<std::size_t>()].name;
}

Row FilesPage::fileRow(std::size_t index) const
{
    return Row{
        Tag{ index },
        Cell{ Tag{ Col::Name }, this, &FilesPage::nameCell }
    };
}

Tag is yours to use however you like — here it carries the row's index into the model. The grid never reads it.

Core Concepts

Columns

Columns form a tree. Any column can have sub-columns:

Column{ Tag{ Col::Range }, Text{ L"Range" },
    Column{ Tag{ Col::RangeMode },   Text{ L"Mode" } },
    Column{ Tag{ Col::RangeAmount }, Text{ L"Amount" } }
}

Anything in a Column that is not another Column is a property. The useful ones:

Rows

Rows appear in the order you declare them. Besides plain Row there are containers that hold other rows:

Cells and content

A row's cells are exactly the ones you declare. Four forms, in one row:

Row{
    // The cell exists and is empty. It still draws a border and can be hovered.
    Cell{ Tag{ Col::Amount } },

    // Text from a lambda.
    Cell{ Tag{ Col::Name }, [](Grids::GetCellTextEvent& event) {
        event.text() << L"...";
    } },

    // Text from a member function - the usual choice.
    Cell{ Tag{ Col::Channel }, this, &Page::channelCell },

    // A live control living in the cell. Its constructor arguments follow the Tag.
    CellWith<CheckBox>{ Tag{ Col::Mute } }
}

A text provider receives the grid's Grids::GetCellTextEvent - the same event a grid-wide OnGetCellText handler takes, so one method serves at either level:

A look every cell of a column shares belongs to the column, not to each provider. Stated as the column's TextFormat - see the Text in Controls manual - it is laid out under the text every cell writes, and it reaches a cell's tooltip and its in-place editor the way it reaches the paint:

Column{ Tag{ Reading::Last }, Text{ L"Last" }, TextAlign::Right, TextFormat{ TextStyleId::Code } }

void FpsPage::writeReading(Grids::GetCellTextEvent& event) const
{
    // The value alone - the column states the style.
    event.text() << Fmt{ L"{}[color muted]{}[/color]", number, unit };
}

A TextAlign the column takes goes in ahead of its TextFormat, so an alignment the format states wins. The header cell is laid out over the alignment alone: it names the column and holds none of its values. None of the format is written into the text a provider receives, so a value accepted from the editor holds what was typed and nothing else.

Merging

Cells grow to cover their neighbours in two ways. Neither is configured — both follow from which cells you declared.

A column whose cell covers its sub-columns

If a row fills a column but none of that column's sub-columns, the cell spans downward over them. The result is always a plain rectangle, because sub-columns exactly cover their parent's width.

This is how one row shows a single wide label while its neighbour shows two separate values under the same parent column.

A group's span row, whose cell covers all of its rows

A Group's span row is stretched to the full height of the rows inside it and drawn across them. They do not collide because the span row and its rows fill different columns: the span row owns the columns that should read as one tall cell, the rows own the rest.

Widths

Each column's width comes from its ColumnWidthMode:

• FitContent — wide enough for its widest cell across all rows.
• Fixed — the width you give it.
• Fill — shares out whatever is left after the others.

A parent column is at least as wide as its sub-columns combined, and the leftover width is distributed among the Fill ones.

Tags

A Tag is the one identifier in play. On a column it is the name cells use to find it; on a row or a control it is yours to use however you like.

Column{ Tag{ Col::Level },   // how cells name this column
    Text{ L"Level" }
}

Row{ Tag{ Kind::Channel, channel },   // yours - the grid never reads it
    Cell{ Tag{ Col::Level }, this, &Page::levelCell }
}

Tag packs several values into one, so a column name can be compound: Tag{ SectionId::Audio, Col::Level }. Reading a segment back is tag.get<index, count, Enum>(), or row.tag<index, count, Enum>() on a row.

Blueprint Reference

import ClaFi.Controls.Grids_Dt;
import ClaFi.Controls.Grids;

namespace MyApp
{
    using namespace ::ClaFi;
    using namespace ::ClaFi::Controls;
    using namespace ::ClaFi::Controls::Grids::Dt;
}

Grid

template <typename... Args>
explicit Grid(const CreateParams& params, Args&&... args);

Grid is the grid itself: an Rt::Grid whose constructor builds the columns, the header and the rows it is handed. The grid's own properties and handlers go in the same list. Add it where any control is added:

Grid& m_grid{ add<Grid>(
    Grids::GridLines::Horizontal,
    OnEvent{ [this](Grids::GetCellTooltipEvent& event) {
        writeHint(event);
    } },
    Columns{ /* ... */ },
    Header{},
    Rows{ /* ... */ }
) };

Column and Columns

Column{ Tag{ ... }, properties..., Column{ ... }, Column{ ... } }

The Tag names the column and may sit anywhere in the argument list — it is an ordinary property, read by the blueprint on its way through. Everything that is not a nested Column is a property, passed straight through to the column. Nested Column nodes become sub-columns.

A column without a Tag is allowed — it simply cannot be named by a cell:

Column{ Text{ L"decorative" }, ShowInHeader::Yes }

Columns{ ... } is a grouping node with no effect on the grid; use it as the outer wrapper.

Row, Expander, Group, Header, Span, Divider, NewItem

Row{ properties..., Cell{ ... }, CellWith<T>{ ... }, aCellSet }

A Row takes no leading key. Properties — anything that is not a cell — go to the row control, so this is where your Tag goes:

Row{
    Tag{ Kind::Device, deviceIndex },
    Cell{ Tag{ Col::Name }, this, &Page::nameCell },
    m_valueCells
}

Every blueprint row can host controls, so nothing special is needed to put one in a cell.

Rows{
    Grids::Dt::Expander{
        Header{ Text{ TextStyleId::SubHeading, L"Outputs" } },
        Group{
            Span{ Tag{ Kind::Group, Device::Mixer },
                Cell{ Tag{ Col::Name }, this, &Page::groupNameCell } },
            channelRow(Channel::Input),
            channelRow(Channel::Output)
        }
    }
}

Header

Header{ ... } is the header of the container it sits directly inside. It is not a row and not a node of any hierarchy: a container looks for one in its own argument list, so it can appear anywhere in that list, and a Header nested a level deeper — inside Rows{}, a Row, a Column — is a compile error rather than a silent no-op.

What it accepts depends on the container, because the two headers are different objects:

Span

Span{ ... } is a group's span row: a row of the group's own, sectioned by the same columns as every other row and laid over the group's rows, so its cells span them. It is a part of the container it sits directly inside, the way a Header is, and only a Group takes one — a Span anywhere else, or a Header in a Group, is a compile error. It takes a Tag, cells and CellWiths, exactly as a Row does.

NewItem

NewItem{ PlaceHolderText{ ... } } is the grid's new-item row. It takes the text its one cell shows and nothing else. Put it in the grid's own list: wherever it is written among the rows, it ends up last, and it stays last as rows are added. What pressing it does is in Adding items from the grid.

Cell, CellWith, CellSet, Init

Cell{ Tag{ ... } }                        // empty but present
Cell{ Tag{ ... }, lambda }                // void(Grids::GetCellTextEvent&)
Cell{ Tag{ ... }, this, &Page::method }   // bound member function
CellWith<T>{ Tag{ ... }, ctorArgs... }    // a live control
CellSet{ cells... }                       // a reusable bundle

The leading Tag on a cell is positional — unlike a column's, it is consumed rather than forwarded, so it has to come first. Everything after it belongs to the control.

CellWith<T> forwards its arguments to the control's constructor. Because the call has to be replayed when the blueprint is applied, those arguments are copied into the node:

For settings that have no constructor property, use Init<T>. It runs against the control immediately after it is created and can appear anywhere in the argument list:

CellWith<Slider>{ Tag{ Col::Amount },
    ScrollButtons::No,
    Init<Slider>{ [](Slider& slider) {
        slider.setMaxPosition(1.0f);
        slider.setRelativePosition(0.5f, false);
    } }
}

Finding things later

The grid answers for everything the blueprint built. The lookups are members of GridBase, and a sub-grid answers them the same as its root:

ComboBox& mode = row.controlAtColumnAs<ComboBox>(m_grid.columnByTag(Tag{ Col::Mode }));

m_grid.forEachRow([this](Grids::Rt::RowContainer& row) {
    refresh(row);
});

Inside a lambda that runs later, capture the tag and resolve it when the event fires. The columns do not exist yet while the blueprint is being built:

OnEvent{ [this, amountTag](ComboBoxChangeEvent& event) {
    auto& row = *static_cast<Grids::Rt::RowContainer*>(event.comboBox().parent());
    Control* slider = row.controlAtColumn(m_grid.columnByTag(amountTag));
    slider->invalidateState();
} }

Recipes

A label that spans sub-columns

Some rows want one wide label where others want two separate values. Declare the parent column's cell and skip the children:

// Device has two sub-columns.
Column{ Tag{ Col::Device }, Text{ L"Device" },
    Column{ Tag{ Col::Name },    ShowInHeader::No },
    Column{ Tag{ Col::Channel }, ShowInHeader::No }
}

// This row fills the parent, so its cell spans both children: one wide label.
Row{ Cell{ Tag{ Col::Device }, this, &Page::deviceCell } }

// This one fills a child instead, so the two sit side by side.
Row{ Cell{ Tag{ Col::Channel }, this, &Page::channelCell } }

Grouping rows beside a span

A Group's span row stretches down its rows. It is a row, so it is described as one:

// The rows fill Channel; the span row fills Name. Together they cover both.
Group{
    Span{
        Tag{ Kind::Group, Device::Mixer },
        Cell{ Tag{ Col::Name }, this, &Page::deviceCell } },
    channelRow(Channel::Input),
    channelRow(Channel::Output)
}

That is the whole recipe. The span's cells connect to the span row exactly as any row's do, so it answers for itself and nothing at grid level is involved.

A control that belongs to the group rather than to a row

The span's cells are stretched over the rows beside them, so a control in one of them reads as the group's own. That is where a choice made once per group goes:

Group{
    Span{
        Tag{ Kind::Group, Device::Mixer },
        Cell{ Tag{ Col::Name }, this, &Page::deviceCell },
        CellWith<CheckBox>{ Tag{ Col::Mute } } },
    channelRow(Channel::Input),
    channelRow(Channel::Output)
}

The control is placed at the top of the merged cell, at the height of one row, and the column it names counts as the span's under the disjointness rule — no row of the group may declare it.

Live controls in cells

A CellWith<T> puts a live control in a cell. The row keeps the keyboard focus for it: the grid keeps the arrows, Home, End, the page keys and Tab, and every other key goes to the control in the selected cell. A key held with Alt goes to the control too, and on to the application's shortcuts when the control has no use for it: Alt+Down drops a combo box's list, and Alt+Left in a browser goes back.

The first click picks the cell. A control that opens something over itself - a combo box's list, an editor typed in place - opens it only from a click on the cell that is already selected. The first click selects the cell and its row, and the next one opens. The dropdown arrow opens on the first click too, because opening the list is its one job. Picking a row to delete it opens nothing.

A check box or a button in a cell acts on the first click. It opens nothing over the cell, so the grid has nothing to hold back.

A click on a control in a cell reaches the grid as a click on the row holding it, which is how the grid moves its selection. A click handler on the grid reads the row in event.control, not the control.

A cell control of your own that drops a popup on a click asks first, and the question it asks says what dropping the popup is to that click. When the answer is no, it leaves the click alone - the click goes on to the row, which picks the cell.

Ctrl+click and Shift+click in a SelectionMode::Multi grid refuse both. A swatch that opens a colour picker when clicked is given that meaning, so it asks the first question:

void SwatchControl::nestedClick(ClickEvent& event)
{
    if (!mayDropPopupImplicitly(event))
        return;
    event.stopPropagation();
    openSwatchPopup();
}

Rows that differ from their neighbours

Build rows with a function and let it choose:

Row Page::channelRow(Channel channel) const
{
    const bool readOnly = channel == Channel::Monitor;
    return Row{
        Tag{ Kind::Channel, channel },
        Cell{ Tag{ Col::Channel }, this, &Page::channelCell },
        readOnly ? m_readOnlyCells : m_valueCells
    };
}

A row that should leave a slot visibly blank rather than let a neighbour cover it declares the cell with no content:

const CellSet m_readOnlyCells{
    Cell{ Tag{ Col::Mode } },      // present, empty, still bordered
    Cell{ Tag{ Col::Amount } }
};

Reaching a control later

void Page::refreshAll()
{
    Grids::Rt::Column& modeColumn = m_grid.columnByTag(Tag{ Col::Mode });
    Grids::Rt::Column& amountColumn = m_grid.columnByTag(Tag{ Col::Amount });
    m_grid.forEachRow([&](Grids::Rt::RowContainer& row) {
        if (row.tag<0, 2, Kind>() != Kind::Channel)
            return;
        ComboBox& mode = row.controlAtColumnAs<ComboBox>(modeColumn);
        Slider& amount = row.controlAtColumnAs<Slider>(amountColumn);
        mode.invalidateState();
        amount.invalidateState();
    });
}

Adding items from the grid

A NewItem row lets the grid ask for an item itself: a muted line under the last row, led by a plus, that reads the text you give it. The grid does the asking and leaves the adding to you:

Grid& m_grid{ add<Grid>(
    Columns{ /* ... */ },
    Header{},
    NewItem{ PlaceHolderText{ L"Add rule" } }
) };

The handler goes in the constructor, once the grid is built:

m_grid.onNewItem([this](Grids::NewItemEvent&) {
    m_rules.push_back({});
    addRuleRow(m_rules.size() - 1);
});

The row's one cell spans every column and behaves like any other cell: the pointer lights it and the arrow keys reach it. A click on it, or Return or Space while it is selected, raises NewItemEvent on the grid. When your handler returns, the grid selects the first cell of the row the handler added, gives it the focus, and scrolls it into view once the row has been laid out. A handler that adds nothing leaves the selection where it was.

A row added after the new-item row is put ahead of it, so it stays last however the rows arrive - appended one at a time or rebuilt wholesale.

To ask for an item from somewhere else - a toolbar button, a shortcut - call grid.requestNewItem(). It raises the same event and selects the same way.

Troubleshooting

Build errors

Nothing appears, or it looks wrong

Do / Don't

Appendix · Direct API

The blueprint is a convenience, not a wall. Everything below works on a grid built from a blueprint as well, which is useful when one row needs something the blueprint does not express.

Without a blueprint, a grid answers two questions through events — which cells exist, and what they say:

m_grid.onCellContent([](Grids::CellContentEvent& event) {
    event.hasContent = event.column().tag() != Tag{ Col::Mute };   // defaults to true
});

m_grid.onGetCellText([this](Grids::GetCellTextEvent& event) {
    writeCell(event);
});

The same two events exist on every row, which is how a blueprint answers for the rows it builds. A row takes a handler for either in its argument list, as an OnEvent like any other, and RowBase::onCellContent / onGetCellText connect one later:

m_grid.addControlRow(Tag{ Kind::Channel, Channel::Input },
    OnEvent{ [](Grids::CellContentEvent& event) {
        event.hasContent = event.column().tag() == Tag{ Col::Channel };
        event.stopPropagation();   // keep the grid handler out of it
    } });