BeepMediaWidget

Overview

BeepMediaWidget 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 10 built-in render modes; changing it at runtime immediately swaps the painter and triggers a repaint.

Toolbox icon: 🖼️
Category: Beep Widgets → Media / Images
Default size: 280 × 200
Namespace: TheTechIdea.Beep.Winform.Controls.Widgets

Key Features

🖼️ Ten Media Styles

Images, galleries, avatars, icons — one widget covers every media type.

🎭 Overlay Support

Built-in text overlay with ShowOverlay toggle for ImageCard/ImageOverlay.

👤 Avatar Clusters

AvatarGroup renders stacked circular thumbnails with overflow count badge.

🎨 Theme Consistent

Border, accent, and hover colours derive automatically from the active theme.

🖱️ Per-Item Events

ImageClicked and AvatarClicked carry individual item data for drill-down.

📐 Gallery & Grid

MediaGallery and PhotoGrid handle multi-image layouts internally.

Style Variants (10)

Style Value	Description
`ImageCard`	Card with a background image and an overlay text strip.
`AvatarGroup`	Stacked circular avatar thumbnails for group display.
`IconCard`	Large centred icon with a title and description below.
`MediaGallery`	Horizontally scrollable image carousel.
`ProfileCard`	User profile card with photo, name, role, and stats.
`ImageOverlay`	Full-bleed image with a semi-transparent text overlay.
`PhotoGrid`	Masonry-style grid of photo thumbnails.
`MediaViewer`	Single large media item with title and metadata.
`AvatarList`	Vertical list of avatars with name and subtitle labels.
`IconGrid`	Grid of icons with labels — ideal for feature showcases.

Properties

Property	Type	Default	Description
`Style`	MediaWidgetStyle	ImageCard	Selects the media painter.
`Title`	string	"Media Title"	Primary caption or heading.
`Subtitle`	string	"Subtitle"	Secondary caption.
`ImagePath`	string	""	File path to the primary display image.
`Image`	Image	null	Directly assigned Image object (takes priority over ImagePath).
`MediaItems`	List<MediaItem>	(empty)	Collection for gallery, grid, and group styles.
`ShowOverlay`	bool	true	Show/hide the text overlay on ImageCard/ImageOverlay.
`OverlayText`	string	"Overlay Text"	Text rendered in the overlay strip.
`AccentColor`	Color	(theme primary)	Accent for icon colours and selection borders.

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

Events

Event	Args Type	Description
`MediaClicked`	BeepEventDataArgs	Fired when anywhere on the widget is clicked.
`ImageClicked`	BeepEventDataArgs	Fired when a specific image/thumbnail is clicked. Data contains MediaItem or index.
`AvatarClicked`	BeepEventDataArgs	Fired when an avatar is clicked in AvatarGroup or AvatarList styles.
`OverlayClicked`	BeepEventDataArgs	Fired when the overlay text area is clicked.

Basic Usage

// Profile card
var profile = new BeepMediaWidget
{
    Style    = MediaWidgetStyle.ProfileCard,
    Title    = "Sarah Connor",
    Subtitle = "Lead Designer",
    ImagePath = "avatars/sarah.png",
    Size     = new Size(240, 180)
};

// Icon grid
var icons = new BeepMediaWidget
{
    Style      = MediaWidgetStyle.IconGrid,
    Title      = "Quick Access",
    MediaItems = new List
    {
        new MediaItem { Title = "Reports",    IconPath = "icons/report.svg"    },
        new MediaItem { Title = "Settings",   IconPath = "icons/settings.svg"  },
        new MediaItem { Title = "Team",       IconPath = "icons/team.svg"      },
        new MediaItem { Title = "Analytics",  IconPath = "icons/analytics.svg" },
    },
    Size = new Size(320, 160)
};

Event Handling

icons.ImageClicked += (s, e) =>
{
    var item = (MediaItem)e.Data;
    NavigateTo(item.Title);
};

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.