BeepListWidget

Overview

BeepListWidget is a paint-based WinForms widget that inherits from BaseControl. It uses an IWidgetPainter pipeline to render rich visuals without child controls. The Style property selects one of 6 built-in render modes; changing it at runtime immediately swaps the painter and triggers a repaint.

Toolbox icon: 📋
Category: Beep Widgets → Data / Lists
Default size: 300 × 250
Namespace: TheTechIdea.Beep.Winform.Controls.Widgets

Key Features

📋 Six List Styles

Activity feeds to ranked tables — flip a property to change the entire layout.

✅ Task Style

TaskList style renders checkboxes and strikethrough text for to-do items.

🔵 Status Indicators

StatusList style renders per-item colour dots linked to the item's Status string.

👤 Profile Rows

ProfileList renders avatars and role subtitles for contact/team lists.

🖱️ Row Selection

AllowSelection enables highlighted row selection with ItemSelected events.

🔢 Scrollable

MaxVisibleItems clips the visible area; internal painted scroll handles overflow.

Style Variants (6)

Style Value	Description
`ActivityFeed`	Timeline-style activity log with timestamps and icons.
`DataTable`	Structured multi-column data table with sortable headers.
`RankingList`	Numbered ranking list with value badges.
`StatusList`	Items each showing a colour-coded status indicator.
`ProfileList`	User/contact listing with avatar placeholder and role subtitle.
`TaskList`	Checklist with checkbox toggle and completion strikethrough.

Properties

Property	Type	Default	Description
`Style`	ListWidgetStyle	ActivityFeed	Selects the list painter.
`Title`	string	"List Title"	Header text drawn above the list.
`Items`	List<ListItem>	(3 sample rows)	Data collection. Each ListItem has Id, Title, Subtitle, Status, Timestamp, IsCompleted.
`Columns`	List<string>	[Name,Value,Status]	Column headers shown in DataTable style.
`ShowHeader`	bool	true	Show/hide the list header row.
`AllowSelection`	bool	true	Enable row click selection.
`SelectedIndex`	int	-1	Currently selected row index.
`MaxVisibleItems`	int	10	Number of rows visible before internal scrolling.
`AccentColor`	Color	(theme primary)	Accent used for status dots, badges, and selected rows.

Inherits all BaseControl properties (Border, Padding, Theme colors, etc.).

Events

Event	Args Type	Description
`ItemClicked`	BeepEventDataArgs	Fired on any list item click. Data contains the clicked ListItem.
`ItemSelected`	BeepEventDataArgs	Fired when selection changes. Data contains the newly selected ListItem.
`HeaderClicked`	BeepEventDataArgs	Fired when a column header is clicked (DataTable style). Data contains column name.

Basic Usage

var list = new BeepListWidget
{
    Style = ListWidgetStyle.StatusList,
    Title = "Service Status",
    Items = new List
    {
        new ListItem { Title = "API Gateway",   Status = "Online",  Subtitle = "99.9% uptime" },
        new ListItem { Title = "Database",      Status = "Online",  Subtitle = "12ms avg" },
        new ListItem { Title = "Cache Layer",   Status = "Warning", Subtitle = "High memory" },
        new ListItem { Title = "Mail Service",  Status = "Offline", Subtitle = "Investigating" },
    },
    Size = new Size(320, 220)
};
this.Controls.Add(list);

Event Handling

list.ItemClicked += (s, e) =>
{
    var item = (ListItem)e.Data;
    ShowServiceDetail(item.Title);
};

list.ItemSelected += (s, e) =>
{
    var item = (ListItem)e.Data;
    statusBar.Text = $"Selected: {item.Title} — {item.Status}";
};

Best Practices

Set Style before adding the widget to the form to avoid double repaints.
Adjust Size to fit your layout — defaults are minimum comfortable sizes.
Read BeepEventDataArgs.Data in event handlers for context-specific click data.
Call Invalidate() after updating data properties to trigger a repaint.
Let theme colors flow from BeepStyling.CurrentTheme — avoid overriding color properties unless customization is explicitly desired.