AlfaToad.CustomControls 3.0.1

AlfaToad.CustomControls

Библиотека пользовательских контролов для Windows Forms (.NET Framework 4.8).

Два основных компонента:

• ExamDataGridView — таблица с привязкой к DataSet / DataTable и настраиваемым оформлением строк.
• ProductCardControl — карточка сущности: изображение, заголовок и набор полей с условиями видимости и стиля.

Пакет: NuGet — AlfaToad.CustomControls

Содержание

• Требования
• Установка
• Быстрый старт
• Панель элементов Visual Studio
• ExamDataGridView
• ProductCardControl
• Тема оформления
• Сборка из исходников
• Структура решения

Требования

Установка

NuGet Package Manager

Install-Package AlfaToad.CustomControls

.NET CLI

dotnet add package AlfaToad.CustomControls

PackageReference

<PackageReference Include="AlfaToad.CustomControls" Version="2.0.2" />

После установки пересоберите проект. Сборка AlfaToad.CustomControls.dll появится в каталоге вывода (например bin\Debug\net48\).

Быстрый старт

using System.Data;
using AlfaToad.CustomControls.Controls;

// --- Таблица ---
var grid = new ExamDataGridView
{
    Dock = DockStyle.Fill,
    DiscountColumnName = "Действующая скидка" // имя столбца в DataTable
};

DataSet dataSet = LoadYourDataSet(); // SqlDataAdapter, ручное заполнение и т.д.
grid.BindDataSet(dataSet, "Products");

// --- Карточка ---
var card = new ProductCardControl
{
    Dock = DockStyle.Fill,
    ImagesFolder = @"C:\App\Data\Images"
};

card.Bind(dataSet.Tables["Products"].Rows[0]);

// Синхронизация: при выборе строки в таблице обновлять карточку
grid.SelectionChanged += (_, __) =>
{
    if (grid.CurrentRow?.DataBoundItem is DataRowView view)
        card.Bind(view.Row);
};

Панель элементов Visual Studio

1. Добавьте ссылку на пакет или проект AlfaToad.CustomControls.
2. Соберите решение.
3. Откройте форму в конструкторе.

В панели элементов должны появиться:

Если контролы не отображаются

1. ПКМ по панели элементов → Выбрать элементы…
2. Вкладка Компоненты .NET Framework
3. Обзор… → укажите AlfaToad.CustomControls.dll
   (путь: packages\AlfaToad.CustomControls\<версия>\lib\net48\ или bin проекта библиотеки)
4. Отметьте нужные типы → ОК

Контролы можно перетаскивать на форму как обычные элементы WinForms.

ExamDataGridView

Наследник DataGridView с поддержкой привязки к DataSet и готовым оформлением.

Привязка данных

Способ 1 — метод:

grid.BindDataSet(dataSet, "TableName", autoGenerateColumns: true);

Способ 2 — свойства:

grid.DataSet = dataSet;
grid.DataMember = "TableName";

Поведение аналогично стандартному DataGridView: источник — DataSet, таблица задаётся через DataMember.

Основные свойства

Подсветка скидки

Если значение в столбце скидки больше 17%, фон ячеек строки меняется на #FFDEAD. Порог и цвета задаются в ExamTheme.

Проверка значения скидки из кода:

if (ExamDataGridView.TryGetDiscountPercent(cellValue, out decimal percent))
{
    // percent — число, символ % в строке учитывается
}

Сброс стиля

grid.ApplyExamStyle();

Применяет шрифт Arial, цвета заголовков и ячеек из ExamTheme.

ProductCardControl

Контрол для отображения одной записи: картинка слева, справа — список полей «подпись / значение».

Привязка к данным

card.Bind(dataRow);

// или по индексу в таблице DataSet
card.Bind(dataSet, "Products", rowIndex: 0);

Изображение

Путь в ячейке может быть только именем файла (ищется в ImagesFolder) или полным путём.

Поля по умолчанию

При создании контрола регистрируются типовые поля (их можно удалить или заменить):

Имена столбцов можно изменить при добавлении своих полей.

Добавление и настройка полей

// Новое поле
card.AddField("Статус", "Статус заказа", "OrderStatus");

// Удаление
card.RemoveField("Единица");

// Доступ к описанию поля
ProductFieldDescriptor field = card.GetField("Цена");
field.Format = "N2";
field.Caption = "Цена, ₽";

Ручное изменение значений

card.SetFieldValue("Цена", 1999.99m);
object value = card.GetFieldValue("Цена");
card.RefreshFromRow(); // перечитать все поля из текущей DataRow
card.Clear();

Условия видимости

card.GetField("Скидка").VisibleWhen = ctx =>
{
    return ExamDataGridView.TryGetDiscountPercent(ctx.Value, out var d) && d > 0;
};

card.GetField("Описание").VisibleWhen = ctx =>
    !string.IsNullOrWhiteSpace(ctx.GetValue<string>("Описание товара"));

ctx — ProductFieldContext: доступ к DataRow, ключу поля и значению; метод GetValue<T>("ColumnName") читает другие столбцы строки.

Условия оформления (фон, цвет текста)

card.GetField("Цена").BackgroundSelector = ctx =>
    ctx.GetValue<decimal>("Цена") > 10_000m
        ? ExamTheme.AccentBackground
        : (Color?)null;

card.GetField("Цена").ForeColorSelector = ctx => Color.DarkRed;

Подсветка высокой скидки

card.ApplyHighDiscountRule("Скидка");

Для поля с ключом Скидка фон строки станет #FFDEAD, если скидка > 17%.

Доступ к строке интерфейса

ProductFieldRowControl row = card.GetFieldRow("Описание");
row.ValueText = "Новый текст";
row.Visible = false;

Событие изменения

card.FieldValueChanged += (s, e) =>
{
    // e.FieldKey, e.Value
};

Тема оформления

Класс AlfaToad.CustomControls.Theme.ExamTheme:

Используется в обоих контролах; при необходимости цвета можно переопределять в коде после ApplyExamStyle().

Сборка из исходников

git clone <ваш-репозиторий>
cd <каталог-решения>
dotnet build DemoExam.sln -c Release

Запуск примера:

dotnet run --project src/DemoExam.Controls.Sample/DemoExam.Controls.Sample.csproj

Локальная сборка пакета:

dotnet pack src/DemoExam.Controls/DemoExam.Controls.csproj -c Release -o ./nupkg

Структура решения

├── README.md
├── DemoExam.sln
├── build/
│   └── AlfaToad.CustomControls.targets   # MSBuild: поддержка дизайнера
├── nupkg/                                 # собранные .nupkg (после pack)
└── src/
    ├── DemoExam.Controls/                 # библиотека AlfaToad.CustomControls
    │   ├── Controls/
    │   ├── Data/
    │   ├── Design/                        # элементы Toolbox
    │   ├── Models/
    │   └── Theme/
    └── DemoExam.Controls.Sample/          # демо-приложение

Пространства имён

Лицензия

Уточните условия использования у автора пакета (поле Authors в NuGet: AlfaToad).