BeepMapWidget

Overview

BeepMapWidget 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 → Maps / Location
Default size: 320 × 220
Namespace: TheTechIdea.Beep.Winform.Controls.Widgets

Key Features

🗺️ Ten Location Styles

From a simple address card to a geographic heatmap — one widget.

📍 Static Map Preview

MapPreview renders a styled placeholder map background with a pin marker.

🌡️ Geographic Heatmap

GeographicHeatmap colours a grid by value intensity.

🛣️ Route Display

RouteDisplay renders an origin→destination path with waypoints.

📋 Location List

LocationList shows multiple locations with distance and direction badges.

🏨 Place Cards

PlaceCard renders venue name, category, and star rating.

Style Variants (10)

Style Value	Description
`LiveTracking`	Real-time dot-on-map location tracker.
`RouteDisplay`	Step-by-step route path visualisation.
`LocationCard`	Card showing address, city, country with a pin icon.
`GeographicHeatmap`	Grid/region heatmap coloured by data density.
`AddressCard`	Formatted postal address with copy action.
`MapPreview`	Small static map preview placeholder with marker.
`LocationList`	Scrollable list of locations with distance badges.
`TravelCard`	Origin-to-destination travel card with transport mode.
`RegionMap`	Simplified regional/country map with data overlay.
`PlaceCard`	Place/venue card with name, photo, category, and rating.

Properties

Property	Type	Default	Description
`Style`	MapWidgetStyle	LocationCard	Selects the map painter.
`Title`	string	"Map Widget"	Card heading.
`Subtitle`	string	"Location Data"	Secondary heading.
`Address`	string	""	Street address.
`City`	string	""	City name.
`Country`	string	""	Country name.
`Latitude`	double	0.0	Decimal latitude for map styles.
`Longitude`	double	0.0	Decimal longitude for map styles.
`Locations`	List<LocationItem>	(empty)	Multiple locations for list/route styles.
`AccentColor`	Color	(theme primary)	Pin and accent colour.

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

Events

Event	Args Type	Description
`LocationClicked`	BeepEventDataArgs	Fired when a map marker or location item is clicked. Data contains LocationItem.
`CardClicked`	BeepEventDataArgs	Fired when the card body is clicked.
`ActionClicked`	BeepEventDataArgs	Fired when an action button (e.g. 'Get Directions') is clicked.

Basic Usage

var location = new BeepMapWidget
{
    Style    = MapWidgetStyle.LocationCard,
    Title    = "Our Office",
    Address  = "123 Tech Avenue",
    City     = "San Francisco",
    Country  = "USA",
    Latitude  = 37.7749,
    Longitude = -122.4194,
    Size     = new Size(300, 160)
};

var route = new BeepMapWidget
{
    Style     = MapWidgetStyle.TravelCard,
    Title     = "Delivery Route",
    Locations = new List
    {
        new LocationItem { Name = "Warehouse",    City = "Oakland"       },
        new LocationItem { Name = "Distribution", City = "San Francisco" },
        new LocationItem { Name = "Customer",     City = "Palo Alto"     },
    },
    Size = new Size(340, 200)
};

Event Handling

location.ActionClicked += (s, e) => OpenMapsApp(location.Latitude, location.Longitude);
route.LocationClicked  += (s, e) =>
{
    var loc = (LocationItem)e.Data;
    ShowLocationDetail(loc.Name);
};

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.