BeepMetricWidget

Overview

BeepMetricWidget 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 / KPI
Default size: 200 × 120
Namespace: TheTechIdea.Beep.Winform.Controls.Widgets

Key Features

📊 Six Visual Modes

From a single plain number to a full card layout with icon — one property switch.

📈 Trend Indicators

Arrow icons with positive/negative colours and percentage labels.

⭕ Circular Gauge

Smooth arc gauge drawn entirely in GDI+ — no external charting library needed.

🎨 Theme-Aware Colors

AccentColor, SuccessColor, and ErrorColor default to the active BeepTheme.

🔔 Click Events

Separate events for value area, trend area, and icon clicks.

📐 Compact Default

200×120 default — fits in tight dashboard grids.

Style Variants (6)

Style Value	Description
`SimpleValue`	Plain number + label – the most compact display.
`ValueWithTrend`	Number plus an arrow trend indicator and percentage change.
`ProgressMetric`	Number with a horizontal progress bar showing completion.
`GaugeMetric`	Circular arc gauge coloured by value range.
`ComparisonMetric`	Two values rendered side-by-side for direct comparison.
`CardMetric`	Card layout with an icon, title, and large value.

Properties

Property	Type	Default	Description
`Style`	MetricWidgetStyle	SimpleValue	Selects the active painter / render mode.
`Title`	string	"Metric Title"	Header label shown above or beside the value.
`Value`	string	"1,234"	Primary displayed value (formatted string).
`Units`	string	""	Optional unit suffix (e.g. "ms", "%", "USD").
`TrendValue`	string	"+12.5%"	Trend label (e.g. "+8.3%", "-2.1%").
`TrendDirection`	string	"up"	"up", "down", or "neutral" — controls arrow direction and colour.
`TrendPercentage`	double	12.5	Numeric percentage used by progress/gauge painters.
`ShowTrend`	bool	false	Show or hide the trend indicator area.
`ShowIcon`	bool	false	Show or hide the icon area (CardMetric style).
`IconPath`	string	""	Path to icon image rendered in the icon area.
`AccentColor`	Color	(theme primary)	Dominant accent colour for bars, arcs, and arrows.
`SuccessColor`	Color	Color(76,175,80)	Colour for positive/upward trends.
`WarningColor`	Color	Color(255,193,7)	Colour for neutral/warning indicators.
`ErrorColor`	Color	Color(244,67,54)	Colour for negative/downward trends.

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

Events

Event	Args Type	Description
`ValueClicked`	BeepEventDataArgs	Fired when the user clicks the value area.
`TrendClicked`	BeepEventDataArgs	Fired when the user clicks the trend indicator.
`IconClicked`	BeepEventDataArgs	Fired when the user clicks the icon area.

Basic Usage

var metric = new BeepMetricWidget
{
    Style         = MetricWidgetStyle.ValueWithTrend,
    Title         = "Monthly Revenue",
    Value         = "$127,450",
    TrendValue    = "+8.3%",
    TrendDirection = "up",
    ShowTrend     = true,
    Size          = new Size(220, 120)
};
this.Controls.Add(metric);

Event Handling

metric.ValueClicked += (s, e) =>
{
    // e.Data contains the current Value string
    ShowRevenueBreakdown(metric.Value);
};

metric.TrendClicked += (s, e) =>
{
    ShowTrendHistory();
};

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.