BeepGrid

Overview

BeepGrid is a sophisticated data grid control that extends the functionality of standard DataGridView with advanced features for enterprise applications. It provides custom column types, integrated filtering, sorting, totals calculation, printing capabilities, and comprehensive data management tools.

Built on the BeepControl foundation, BeepGrid features a modular panel system with customizable header, filter, totals, and navigation panels. It supports dynamic column creation from EntityStructure, layout persistence, and seamless integration with data sources through the Beep framework.

Key Features

Basic Usage

// Create a basic BeepGrid
var grid = new BeepGrid
{
    Size = new Size(800, 400),
    Location = new Point(10, 10),
    ShowHeaderPanel = true,
    ShowFilterPanel = false,
    ShowTotalsPanel = false,
    ShowNavigatorPanel = true
};

// Set data source
var dataTable = GetSampleData();
grid.DataSource = dataTable;

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

// Create grid with entity-based columns
var grid = new BeepGrid();
grid.SetConfig(dmeEditor, logger, util, null, null, null);

// Define entity structure
var entityStructure = new EntityStructure
{
    EntityName = "Employees",
    Fields = new List
    {
        new EntityField {FieldName = "ID", Fieldtype = "System.Int32" },
        new EntityField {FieldName = "Name", Fieldtype = "System.String" },
        new EntityField {FieldName = "Salary", Fieldtype = "System.Decimal" },
        new EntityField {FieldName = "HireDate", Fieldtype = "System.DateTime" },
        new EntityField {FieldName = "IsActive", Fieldtype = "System.Boolean" }
    }
};

// Reset grid with data and entity
var employees = GetEmployeeData();
grid.ResetData(employees, entityStructure);

var grid = new BeepGrid
{
    Size = new Size(1000, 600),
    
    // Panel visibility
    ShowHeaderPanel = true,      // Show title and action buttons
    ShowColumnHeaderPanel = true, // Show custom column headers
    ShowFilterPanel = true,       // Show filter row
    ShowTotalsPanel = true,       // Show totals row
    ShowNavigatorPanel = true,    // Show navigation controls
    
    // Grid properties
    AllowUserToAddRows = false,
    AllowUserToDeleteRows = true,
    ReadOnly = false
};

// Configure title
grid.Title.Text = "Employee Management Grid";

// Handle events
grid.CellDoubleClick += (s, e) => {
    if (e.RowIndex >= 0)
    {
        var employee = GetEmployeeFromRow(e.RowIndex);
        EditEmployee(employee);
    }
};

Custom Column Types

BeepGrid provides specialized column types for different data scenarios:

// Clear auto-generated columns
grid.Columns.Clear();

// Add progress bar column
var performanceColumn = new BeepDataGridViewProgressBarColumn
{
    Name = "Performance",
    HeaderText = "Performance",
    DataPropertyName = "PerformanceScore",
    ProgressBarColor = Color.Green,
    Minimum = 0,
    Maximum = 100,
    Width = 150
};
grid.Columns.Add(performanceColumn);

// Add combo box column
var departmentColumn = new BeepDataGridViewComboBoxColumn
{
    Name = "Department",
    HeaderText = "Department",
    DataPropertyName = "DepartmentId",
    DisplayMember = "Name",
    ValueMember = "Id",
    Width = 130
};
departmentColumn.DataSource = GetDepartments();
grid.Columns.Add(departmentColumn);

// Add rating column
var ratingColumn = new BeepDataGridViewRatingColumn
{
    Name = "Rating",
    HeaderText = "Performance Rating",
    DataPropertyName = "Rating",
    MaxStars = 5,
    Width = 140
};
grid.Columns.Add(ratingColumn);

Properties

Core Properties

Panel Visibility Properties

Component Access Properties

Methods

// Initialize grid with framework components
grid.SetConfig(dmeEditor, logger, utilities, args, passedArgs, errorInfo);

// Reset with new data and entity
var result = grid.ResetData(customerData, customerEntityStructure);
if (result.Flag == Errors.Ok)
{
  //  Console.WriteLine("Grid reset successfully");
}

// Create columns from entity structure
grid.EntityStructure = productEntityStructure;
grid.CreateColumnsForEntity();

// Refresh grid display
grid.RefreshGrid();

// Save/load layout for persistence
grid.SaveGridLayout();
grid.LoadGridLayout();

Events

var grid = new BeepGrid();

// Handle cell interactions
grid.CellDoubleClick += (s, e) => {
    if (e.RowIndex >= 0 && e.ColumnIndex >= 0)
    {
        var value = grid[e.ColumnIndex, e.RowIndex].Value;
      //  Console.WriteLine($"Double-clicked: {value}");
        
        // Open edit dialog
        EditRecord(e.RowIndex);
    }
};

// Handle data operations
grid.SaveCalled += (s, e) => {
    try
    {
        SaveChangesToDatabase(e.DataSource);
        MessageBox.Show("Changes saved successfully");
    }
    catch (Exception ex)
    {
        MessageBox.Show($"Save failed: {ex.Message}");
    }
};

// Handle formatting
grid.CellFormatting += (s, e) => {
    if (e.ColumnIndex == salaryColumnIndex && e.Value != null)
    {
        if (decimal.TryParse(e.Value.ToString(), out decimal salary))
        {
            e.CellStyle.BackColor = salary > 50000 ? Color.LightGreen : Color.LightPink;
            e.FormattingApplied = true;
        }
    }
};

Examples

public void CreateEmployeeGrid()
{
    var employeeGrid = new BeepGrid
    {
        Size = new Size(1200, 600),
        Location = new Point(10, 10),
        ShowHeaderPanel = true,
        ShowFilterPanel = true,
        ShowTotalsPanel = true,
        ShowNavigatorPanel = true
    };

    // Configure grid
    employeeGrid.SetConfig(dmeEditor, logger, utilities, null, null, null);
    employeeGrid.Title.Text = "Employee Management System";

    // Define entity structure
    var employeeEntity = new EntityStructure
    {
        EntityName = "Employees",
        Fields = new List
        {
            new EntityField {FieldName = "EmployeeID", Fieldtype = "System.Int32" },
            new EntityField {FieldName = "FirstName", Fieldtype = "System.String" },
            new EntityField {FieldName = "LastName", Fieldtype = "System.String" },
            new EntityField {FieldName = "Email", Fieldtype = "System.String" },
            new EntityField {FieldName = "HireDate", Fieldtype = "System.DateTime" },
            new EntityField {FieldName = "Salary", Fieldtype = "System.Decimal" },
            new EntityField {FieldName = "Department", Fieldtype = "System.String" },
            new EntityField {FieldName = "IsActive", Fieldtype = "System.Boolean" },
            new EntityField {FieldName = "Performance", Fieldtype = "System.Int32" }
        }
    };

    // Get employee data and reset grid
    var employees = GetEmployeeData();
    employeeGrid.ResetData(employees, employeeEntity);

    // Customize specific columns
    CustomizeEmployeeColumns(employeeGrid);

    this.Controls.Add(employeeGrid);
}

public class ProductCatalogGrid : UserControl
{
    private BeepGrid productGrid;

    public ProductCatalogGrid()
    {
        InitializeProductGrid();
        LoadProductData();
    }

    private void InitializeProductGrid()
    {
        productGrid = new BeepGrid
        {
            Dock = DockStyle.Fill,
            ShowHeaderPanel = true,
            ShowFilterPanel = true,
            ShowTotalsPanel = true,
            ShowNavigatorPanel = true
        };

        productGrid.Title.Text = "Product Catalog";
        CreateProductColumns();
        this.Controls.Add(productGrid);
    }

    private void CreateProductColumns()
    {
        productGrid.Columns.Clear();

        // Product Name
        productGrid.Columns.Add(new DataGridViewTextBoxColumn
        {
            Name = "ProductName",
            HeaderText = "Product Name",
            DataPropertyName = "ProductName",
            Width = 200
        });

        // Category ComboBox
        var categoryColumn = new BeepDataGridViewComboBoxColumn
        {
            Name = "Category",
            HeaderText = "Category",
            DataPropertyName = "CategoryID",
            DisplayMember = "CategoryName",
            ValueMember = "CategoryID",
            Width = 150
        };
        categoryColumn.DataSource = GetCategories();
        productGrid.Columns.Add(categoryColumn);

        // Price with formatting
        var priceColumn = new BeepDataGridViewNumericColumn
        {
            Name = "Price",
            HeaderText = "Unit Price",
            DataPropertyName = "UnitPrice",
            DefaultCellStyle = { Format = "C2" },
            Width = 100
        };
        productGrid.Columns.Add(priceColumn);

        // Stock Level Progress Bar
        var stockColumn = new BeepDataGridViewProgressBarColumn
        {
            Name = "StockLevel",
            HeaderText = "Stock Level",
            DataPropertyName = "UnitsInStock",
            ProgressBarColor = Color.Orange,
            Minimum = 0,
            Maximum = 100,
            Width = 120
        };
        productGrid.Columns.Add(stockColumn);

        // Rating
        var ratingColumn = new BeepDataGridViewRatingColumn
        {
            Name = "Rating",
            HeaderText = "Customer Rating",
            DataPropertyName = "Rating",
            MaxStars = 5,
            Width = 130
        };
        productGrid.Columns.Add(ratingColumn);
    }
}

public void CreateConfigurableGrid()
{
    var configurableGrid = new BeepGrid
    {
        GridId = "ConfigurableDataGrid", // For layout persistence
        Size = new Size(900, 500)
    };

    // Column configurations for advanced scenarios
    var columnConfigs = new List
    {
        new BeepColumnConfig
        {
            ColumnName = "ID",
            ColumnCaption = "Record ID",
            Width = 80,
            IsFilteOn = false,
            IsTotalOn = false
        },
        new BeepColumnConfig
        {
            ColumnName = "Amount",
            ColumnCaption = "Transaction Amount",
            Width = 120,
            IsFilteOn = true,
            IsTotalOn = true,
            HasTotal = true
        }
    };

    configurableGrid.ColumnsConfigurations = columnConfigs;

    // Enable all panels for full functionality
    configurableGrid.ShowHeaderPanel = true;
    configurableGrid.ShowFilterPanel = true;
    configurableGrid.ShowTotalsPanel = true;
    configurableGrid.ShowNavigatorPanel = true;

    // Load and save layout automatically
    configurableGrid.LoadGridLayout();
    
    // Save layout when form closes
    this.FormClosing += (s, e) => {
        configurableGrid.SaveGridLayout();
    };
}

Filtering & Sorting

BeepGrid provides powerful filtering and sorting capabilities:

// Show filter panel
grid.ShowFilterPanel = true;

// Filters are automatically available for each column
// Users can type in filter boxes to filter data

// Programmatic filtering example
private void ApplyCustomFilter()
{
    // Access the binding source for complex filtering
    var bindingSource = grid.BindingNavigator.BindingSource;
    
    // Apply complex filter
    bindingSource.Filter = "Salary > 50000 AND Department = 'Engineering'";
    
    // Remove filter
    bindingSource.RemoveFilter();
}

// Sorting is automatically enabled on column headers
// Click to sort, click again to reverse, third click to remove sort

// Programmatic sorting
grid.Sort(grid.Columns["Salary"], ListSortDirection.Descending);

// Handle sort events
grid.GridView.Sorted += (s, e) => {
  //  Console.WriteLine("Grid sorted");
    UpdateTotalCalculations();
};

// Enable totals panel
grid.ShowTotalsPanel = true;

// Totals are automatically calculated for numeric columns
// Custom total calculation can be implemented through column configs

// Access calculated totals
foreach (var config in grid.ColumnsConfigurations)
{
    if (config.HasTotal && config.IsTotalOn)
    {
      //  Console.WriteLine($"{config.ColumnName}: {config.Total}");
    }
}

Theming

BeepGrid provides comprehensive theming support for all components:

var grid = new BeepGrid
{
    Theme = "DarkTheme"
};

// Theme automatically applies to:
// - Grid background and foreground colors
// - Selected row colors
// - Header styling
// - Panel backgrounds
// - Button and control styling

// Apply theme manually if needed
grid.ApplyTheme();

Theme-Responsive Features

• Grid Colors - Background, foreground, and selection colors
• Header Styling - Column headers adapt to theme colors
• Panel Backgrounds - All panels use consistent theme colors
• Custom Columns - Specialized columns respect theme settings
• Controls - Navigation and action buttons use theme styling

Best Practices

⚡ Performance

• Virtual Mode: Use virtual mode for large datasets (>10,000 rows)
• Column Types: Use appropriate column types for better performance and UX
• Data Binding: Bind to proper data sources (DataTable, BindingList, etc.)
• Layout Persistence: Use GridId for automatic layout saving/loading
• Suspend Layout: Suspend layout during bulk column operations

📊 Data Management

• Entity Structure: Define proper EntityStructure for automatic column generation
• Data Validation: Implement cell validation for data integrity
• Error Handling: Handle DataError events for robust applications
• Transaction Support: Use transactions for data modifications

🎨 User Experience

• Panel Configuration: Show/hide panels based on user needs
• Column Sizing: Set appropriate default column widths
• Filtering: Enable filtering for searchable data sets
• Sorting: Ensure sortable columns are properly configured
• Visual Feedback: Use formatting and custom columns for better data visualization

♿ Accessibility

• Keyboard Navigation: Ensure full keyboard accessibility
• Screen Readers: Use meaningful column headers and descriptions
• High Contrast: Test with high contrast themes
• Focus Indicators: Provide clear focus indication