BeepCard

Overview

BeepCard is a versatile card component that displays content in a structured format with an optional image, header text, paragraph text, and action button. It supports multiple view modes for different layout requirements and provides interactive click areas for each element.

Built on top of the BeepControl base class, BeepCard combines BeepImage, BeepLabel, and BeepButton components to create a cohesive, themeable card interface suitable for dashboards, product displays, user profiles, and content presentation.

Key Features

View Modes

BeepCard supports three distinct view modes for different layout requirements:

Basic Usage

// Create a basic BeepCard
var card = new BeepCard
{
    HeaderText = "Welcome",
    ParagraphText = "This is a sample card with basic content.",
    ButtonText = "Learn More",
    Size = new Size(300, 200),
    Location = new Point(10, 10)
};

// Add to form
this.Controls.Add(card);

var imageCard = new BeepCard
{
    HeaderText = "Product Card",
    ParagraphText = "Premium quality product with excellent features.",
    ButtonText = "Buy Now",
    ImagePath = "images/product.jpg",
    ViewMode = CardViewMode.FullImage,
    MaxImageSize = 120,
    Size = new Size(280, 320)
};

var infoCard = new BeepCard
{
    HeaderText = "Notification",
    ParagraphText = "Your account has been successfully updated.",
    ViewMode = CardViewMode.Compact,
    ShowButton = false,
    Size = new Size(300, 120),
    IsRounded = true,
    BorderRadius = 8
};

Properties

Content Properties

Image Properties

Layout Properties

Events

var card = new BeepCard
{
    HeaderText = "Interactive Card",
    ParagraphText = "Click different areas to see events in action.",
    ButtonText = "Primary Action",
    ImagePath = "images/sample.jpg"
};

// Handle different click areas
card.ImageClicked += (s, e) => {
    MessageBox.Show("Image clicked! Opening gallery...");
    OpenImageGallery(card.ImagePath);
};

card.HeaderClicked += (s, e) => {
    MessageBox.Show("Header clicked! Opening details...");
    ShowDetailsDialog(card.HeaderText);
};

card.ParagraphClicked += (s, e) => {
    MessageBox.Show("Paragraph clicked! Expanding text...");
    ShowExpandedText(card.ParagraphText);
};

card.ButtonClicked += (s, e) => {
    MessageBox.Show("Button clicked! Performing action...");
    PerformPrimaryAction();
};

Examples

public void CreateProductCards()
{
    var products = new[]
    {
        new { Name = "Laptop Pro", Price = "$1,299", Image = "laptop.jpg" },
        new { Name = "Smartphone X", Price = "$899", Image = "phone.jpg" },
        new { Name = "Tablet Plus", Price = "$599", Image = "tablet.jpg" }
    };

    var panel = new FlowLayoutPanel 
    { 
        Dock = DockStyle.Fill, 
        FlowDirection = FlowDirection.LeftToRight,
        WrapContents = true,
        Padding = new Padding(10)
    };

    foreach (var product in products)
    {
        var card = new BeepCard
        {
            HeaderText = product.Name,
            ParagraphText = $"Premium quality device starting at {product.Price}",
            ButtonText = "Add to Cart",
            ImagePath = $"images/{product.Image}",
            ViewMode = CardViewMode.FullImage,
            Size = new Size(250, 320),
            Margin = new Padding(10),
            IsRounded = true,
            BorderRadius = 12,
            ShowShadow = true
        };

        card.ButtonClicked += (s, e) => {
            AddToCart(product.Name);
            ShowNotification($"{product.Name} added to cart!");
        };

        panel.Controls.Add(card);
    }

    this.Controls.Add(panel);
}

public BeepCard CreateUserProfile(string name, string role, string avatar)
{
    var profileCard = new BeepCard
    {
        HeaderText = name,
        ParagraphText = $"Role: {role}\nDepartment: Engineering\nLocation: San Francisco",
        ButtonText = "View Profile",
        ImagePath = avatar,
        ViewMode = CardViewMode.ImageLeft,
        Size = new Size(400, 150),
        MaxImageSize = 80,
        IsRounded = true,
        BorderRadius = 8
    };

    profileCard.ImageClicked += (s, e) => {
        ShowProfilePicture(avatar);
    };

    profileCard.HeaderClicked += (s, e) => {
        OpenUserDetails(name);
    };

    profileCard.ButtonClicked += (s, e) => {
        OpenFullProfile(name);
    };

    return profileCard;
}

public void CreateStatusDashboard()
{
    var statusData = new[]
    {
        new { Title = "Server Status", Value = "Online", Icon = "server-ok.svg", Color = Color.Green },
        new { Title = "Database", Value = "Connected", Icon = "database.svg", Color = Color.Blue },
        new { Title = "API Calls", Value = "1,234", Icon = "api.svg", Color = Color.Orange },
        new { Title = "Users Online", Value = "56", Icon = "users.svg", Color = Color.Purple }
    };

    var dashboardPanel = new TableLayoutPanel
    {
        ColumnCount = 2,
        RowCount = 2,
        Dock = DockStyle.Fill,
        Padding = new Padding(10)
    };

    foreach (var status in statusData)
    {
        var statusCard = new BeepCard
        {
            HeaderText = status.Title,
            ParagraphText = status.Value,
            ImagePath = status.Icon,
            ViewMode = CardViewMode.ImageLeft,
            ShowButton = false,
            Size = new Size(200, 100),
            MaxImageSize = 32,
            IsRounded = true,
            BorderRadius = 6,
            Margin = new Padding(5)
        };

        // Apply status-specific styling
        statusCard.ForeColor = status.Color;

        dashboardPanel.Controls.Add(statusCard);
    }

    this.Controls.Add(dashboardPanel);
}

public BeepCard CreateNewsCard(string headline, string summary, string imageUrl, DateTime publishDate)
{
    var newsCard = new BeepCard
    {
        HeaderText = headline,
        ParagraphText = $"{summary}\n\nPublished: {publishDate:MMM dd, yyyy}",
        ButtonText = "Read More",
        ImagePath = imageUrl,
        ViewMode = CardViewMode.FullImage,
        Size = new Size(300, 280),
        HeaderAlignment = ContentAlignment.TopLeft,
        TextAlignment = ContentAlignment.TopLeft,
        UseGradientBackground = true,
        IsRounded = true,
        BorderRadius = 10
    };

    newsCard.ButtonClicked += (s, e) => {
        OpenArticle(headline);
    };

    newsCard.HeaderClicked += (s, e) => {
        OpenArticlePreview(headline);
    };

    return newsCard;
}

Theming

BeepCard supports comprehensive theming with specific card styling properties:

var themedCard = new BeepCard
{
    HeaderText = "Themed Card",
    ParagraphText = "This card uses automatic theme styling.",
    ButtonText = "Action",
    Theme = "ModernDark"
};

// Automatically applies:
// - CardBackColor for background
// - CardHeaderStyle for header font and color
// - CardTextForeColor for paragraph text
// - CardparagraphStyle for paragraph font
// - Button theme styling

Card Theme Properties

• CardBackColor - Card background color
• CardHeaderStyle - Header typography and color
• CardTextForeColor - Paragraph text color
• CardparagraphStyle - Paragraph typography
• CardTitleForeColor - Used for title accents
• BorderRadius - Corner radius styling
• ShadowColor/ShadowOpacity - Shadow effects

public void CreateCustomStyledCard()
{
    var customCard = new BeepCard
    {
        HeaderText = "Custom Styled Card",
        ParagraphText = "This card has custom styling overrides.",
        ButtonText = "Custom Action",
        Size = new Size(300, 200),
        
        // Custom styling
        BackColor = Color.FromArgb(245, 245, 250),
        ForeColor = Color.FromArgb(50, 50, 70),
        IsRounded = true,
        BorderRadius = 15,
        ShowShadow = true,
        UseGradientBackground = true
    };

    // Apply theme after setting custom properties
    customCard.ApplyTheme();
}

Best Practices

🎨 Design Guidelines

• Content hierarchy: Keep headers concise, paragraphs informative but brief
• View mode selection: Use FullImage for media content, ImageLeft for lists, Compact for text-only
• Button text: Use action-oriented button text (Buy Now, Learn More, View Details)
• Image quality: Use high-quality images with appropriate aspect ratios
• Consistent sizing: Maintain consistent card dimensions within collections

⚡ Performance

• Image optimization: Use appropriately sized images to prevent scaling overhead
• Card collections: Consider virtualization for large numbers of cards
• Event handlers: Dispose of event handlers properly when removing cards
• Theme caching: Let the theme system manage font and color caching
• Layout efficiency: Use FlowLayoutPanel or TableLayoutPanel for card collections

♿ Accessibility

• Keyboard navigation: Ensure cards can be navigated via keyboard
• Screen readers: Provide meaningful header and paragraph text
• Color contrast: Maintain sufficient contrast for text readability
• Click areas: Ensure interactive areas have adequate size
• Focus indicators: Provide clear visual feedback for focused elements

🔧 Technical Considerations

• Event handling: Use specific area events for granular interaction control
• Layout updates: Card layout updates automatically when properties change
• Memory management: Dispose of cards properly when removing from collections
• Hit testing: The card automatically manages hit areas for different regions
• Data binding: Consider binding card properties to data objects for dynamic content