Tesserae - Grid Picker

GridPicker

Description

The GridPicker component creates an interactive grid of buttons, where each cell can have multiple states. It is used for building grid-based state selectors and pickers, such as scheduling interfaces or game boards. The component is part of the Tesserae UI Components group and leverages a fluent interface to configure button appearance and behavior based on the state.

Usage

Create a GridPicker instance by providing arrays of column and row names, the number of states each cell can have, an initial state for every cell, and a function to format each button based on its state. Optionally, you can provide custom column sizes and row heights.

Below is a simple usage example:

grid-picker-sample.js

using System;
using System.Collections.Generic;
using System.Linq;
using System.Threading.Tasks;
using H5.Core;
using Tesserae;
using static H5.Core.dom;
using static Tesserae.UI;

namespace Tesserae.Tests
{
    internal static class App
    {
        private static void Main()
        {
            var sampleComponent = new SampleGridPickerUsage();
            document.body.style.overflow = "hidden";
            MountCenteredToBody(sampleComponent);
        }
    }

    public class SampleGridPickerUsage : IComponent
    {
        public HTMLElement Render()
        {
            // Define column and row headers.
            var columns = new[] { "Mon", "Tue", "Wed", "Thu", "Fri" };
            var rows = new[] { "Morning", "Afternoon", "Evening" };

            // Create initial states (all zeros) for each cell in the grid.
            var initialStates = Enumerable.Range(0, rows.Length)
                                          .Select(_ => new int[columns.Length])
                                          .ToArray();

            // Define how each state should be formatted. In this example, we show an emoji.
            Action<Button, int, int> formatState = (btn, state, previousState) =>
            {
                string text;
                switch (state)
                {
                    case 0: text = "Off"; break;
                    case 1: text = "On";  break;
                    default: text = "?";  break;
                }
                btn.SetText(text);
            };

            // Instantiate the GridPicker.
            var gridPicker = GridPicker(
                columnNames: columns,
                rowNames: rows,
                states: 2,
                initialStates: initialStates,
                formatState: formatState
            );

            return gridPicker.Render();
        }
    }
}

API reference

class

GridPicker

public sealed class GridPicker : IComponent

A GridPicker component that allows users to select states across a grid of buttons, supporting drag-to-select functionality.

Constructors

Constructor

GridPicker

public GridPicker(string[] columnNames, string[] rowNames, int states, int[][] initialStates, Action<Button, int, int> formatState, UnitSize[] columns = null, UnitSize rowHeight = null)

Initializes a new instance of the GridPicker class.

Parameters

columnNames: Names of the columns.
rowNames: Names of the rows.
states: Number of available states for each grid cell.
initialStates: Initial state values for each cell.
formatState: An action to format the button based on its state.
columns: Optional column widths.
rowHeight: Optional row height.

Properties

Property

GridPicker.IsDragging

public bool IsDragging

Gets whether the grid picker is currently being dragged.

Methods

Method

GridPicker.GetState

public int[][] GetState()

Gets the current state of the grid picker.

Returns

A 2D array representing the states.

Method

GridPicker.SetState

public GridPicker SetState(int[][] state)

Sets the current state of the grid picker.

Parameters

state: A 2D array representing the new states.

Returns

The current instance of the type.

Method

GridPicker.OnChange

public GridPicker OnChange(ComponentEventHandler<GridPicker, Event> onChange)

Adds a change event handler to the grid picker.

Parameters

onChange: The event handler.

Returns

The current instance of the type.

Method

GridPicker.Render

public HTMLElement Render()

Renders the grid picker.

Returns

The rendered HTMLElement.

Samples

Basic GridPicker Example

The following sample demonstrates how to instantiate a simple GridPicker with two states. Each cell displays different text based on its current state.

grid-picker-5-sample.js

using System;
using System.Collections.Generic;
using System.Linq;
using System.Threading.Tasks;
using H5.Core;
using Tesserae;
using static H5.Core.dom;
using static Tesserae.UI;

namespace Tesserae.Tests
{
    internal static class App
    {
        private static void Main()
        {
            var sampleComponent = new BasicGridPickerExample();
            document.body.style.overflow = "hidden";
            MountCenteredToBody(sampleComponent);
        }
    }

    public class BasicGridPickerExample : IComponent
    {
        public HTMLElement Render()
        {
            var columns = new[] { "Mon", "Tue", "Wed", "Thu", "Fri", "Sat", "Sun" };
            var rows = new[] { "Morning", "Afternoon", "Evening" };

            var initialStates = Enumerable.Range(0, rows.Length)
                                          .Select(_ => new int[columns.Length])
                                          .ToArray();

            Action<Button, int, int> formatState = (btn, state, previousState) =>
            {
                string text;
                switch (state)
                {
                    case 0: text = "☠"; break;
                    case 1: text = "🐢"; break;
                    default: text = "??"; break;
                }

                // Display transition if previous state is provided
                if (previousState >= 0 && previousState != state)
                {
                    string prevText;
                    switch (previousState)
                    {
                        case 0: prevText = "☠"; break;
                        case 1: prevText = "🐢"; break;
                        default: prevText = "??"; break;
                    }
                    text = $"{prevText} -> {text}";
                }
                btn.SetText(text);
            };

            var gridPicker = GridPicker(
                columnNames: columns,
                rowNames: rows,
                states: 2,
                initialStates: initialStates,
                formatState: formatState
            );

            return gridPicker.Render();
        }
    }
}

Advanced GridPicker for Hourly Schedule

This sample shows how to create an hourly schedule picker by dynamically generating column headers for each hour of the day.

grid-picker-6-sample.js

using System;
using System.Collections.Generic;
using System.Linq;
using System.Threading.Tasks;
using H5.Core;
using Tesserae;
using static H5.Core.dom;
using static Tesserae.UI;

namespace Tesserae.Tests
{
    internal static class App
    {
        private static void Main()
        {
            var sampleComponent = new HourlyScheduleGridPicker();
            document.body.style.overflow = "hidden";
            MountCenteredToBody(sampleComponent);
        }
    }

    public class HourlyScheduleGridPicker : IComponent
    {
        public HTMLElement Render()
        {
            var days = new[] { "Monday", "Tuesday", "Wednesday", "Thursday", "Friday", "Saturday", "Sunday" };
            var hours = Enumerable.Range(0, 24).Select(n => $"{n:00}").ToArray();

            var initialStates = days.Select(_ => new int[hours.Length]).ToArray();

            Action<Button, int, int> formatState = (btn, state, previousState) =>
            {
                string color;
                switch (state)
                {
                    case 0: color = "#c7c5c5"; break;
                    case 1: color = "#a3cfa5"; break;
                    case 2: color = "#76cc79"; break;
                    case 3: color = "#1fcc24"; break;
                    default: color = "#ffffff"; break;
                }

                btn.Background(color);
            };

            // Optional: Providing custom column sizes and row height.
            var gridPicker = GridPicker(
                rowNames: days,
                columnNames: hours,
                states: 4,
                initialStates: initialStates,
                formatState: formatState,
                columns: new[] { 128.px(), 24.px() },
                rowHeight: 24.px()
            );

            return gridPicker.Render();
        }
    }
}

GridPicker

Description

Usage

API reference

Constructors

GridPicker

Parameters

Properties

GridPicker.IsDragging

Methods

GridPicker.GetState

Returns

GridPicker.SetState

Parameters

Returns

GridPicker.OnChange

Parameters

Returns

GridPicker.Render

Returns

Samples

Basic GridPicker Example

Advanced GridPicker for Hourly Schedule

See also