Доработан проект UI под новый Core

2026-01-25 02:52:07 +03:00
parent be12154262
commit 2bd7d3c474
7 changed files with 923 additions and 181 deletions
--- a/Lattice.UI.DragDrop/Abstractions/IDragDropHost.cs
+++ b/Lattice.UI.DragDrop/Abstractions/IDragDropHost.cs
@@ -5,37 +5,77 @@ namespace Lattice.UI.DragDrop.Abstractions;
 /// <summary>
 /// Хост для отображения визуальных элементов перетаскивания.
 /// </summary>
+/// <remarks>
+/// <para>
+/// Интерфейс предоставляет абстракцию для управления визуальными элементами
+/// перетаскивания в различных UI-фреймворках (WPF, Avalonia, MAUI и т.д.).
+/// </para>
+/// <para>
+/// Реализация должна обеспечивать корректное отображение визуальных элементов
+/// поверх других элементов UI и их своевременное удаление при завершении операций.
+/// </para>
+/// </remarks>
 public interface IDragDropHost
 {
    /// <summary>
-    /// Показывает визуальное представление перетаскивания.
+    /// Показывает визуальное представление перетаскиваемого элемента.
    /// </summary>
-    /// <param name="dragVisual">Визуальное представление.</param>
-    /// <param name="position">Начальная позиция.</param>
+    /// <param name="dragVisual">Визуальное представление элемента для перетаскивания.</param>
+    /// <param name="position">Начальная позиция визуального элемента в экранных координатах.</param>
+    /// <remarks>
+    /// <para>
+    /// Метод должен отобразить переданный визуальный элемент в указанной позиции.
+    /// Визуальный элемент должен следовать за курсором мыши при обновлении через <see cref="UpdateDragVisualPosition"/>.
+    /// </para>
+    /// <para>
+    /// Визуальный элемент должен отображаться поверх всех других элементов интерфейса.
+    /// </para>
+    /// </remarks>
    void ShowDragVisual(object dragVisual, Point position);

    /// <summary>
    /// Обновляет позицию визуального представления перетаскивания.
    /// </summary>
-    /// <param name="dragVisual">Визуальное представление.</param>
-    /// <param name="position">Новая позиция.</param>
+    /// <param name="dragVisual">Визуальное представление, позиция которого должна быть обновлена.</param>
+    /// <param name="position">Новая позиция в экранных координатах.</param>
+    /// <remarks>
+    /// Метод должен обновлять позицию уже отображаемого визуального элемента
+    /// с минимальной задержкой для плавного перемещения.
+    /// </remarks>
    void UpdateDragVisualPosition(object dragVisual, Point position);

    /// <summary>
    /// Скрывает визуальное представление перетаскивания.
    /// </summary>
-    /// <param name="dragVisual">Визуальное представление.</param>
+    /// <param name="dragVisual">Визуальное представление для скрытия.</param>
+    /// <remarks>
+    /// После вызова этого метода визуальный элемент должен быть полностью
+    /// удален из визуального дерева и его ресурсы освобождены.
+    /// </remarks>
    void HideDragVisual(object dragVisual);

    /// <summary>
    /// Показывает визуальную обратную связь для цели сброса.
    /// </summary>
-    /// <param name="adorner">Элемент обратной связи.</param>
+    /// <param name="adorner">Элемент обратной связи для отображения.</param>
+    /// <remarks>
+    /// <para>
+    /// Метод должен отобразить элемент обратной связи (например, подсветку, рамку или индикатор позиции)
+    /// для визуального указания возможности сброса на целевой элемент.
+    /// </para>
+    /// <para>
+    /// Элемент обратной связи должен отображаться поверх целевого элемента, но под перетаскиваемым визуальным элементом.
+    /// </para>
+    /// </remarks>
    void ShowDropAdorner(IDropVisualAdorner adorner);

    /// <summary>
    /// Скрывает визуальную обратную связь для цели сброса.
    /// </summary>
-    /// <param name="adorner">Элемент обратной связи.</param>
+    /// <param name="adorner">Элемент обратной связи для скрытия.</param>
+    /// <remarks>
+    /// После вызова этого метода элемент обратной связи должен быть
+    /// удален из визуального дерева и его ресурсы освобождены.
+    /// </remarks>
    void HideDropAdorner(IDropVisualAdorner adorner);
 }
--- a/Lattice.UI.DragDrop/Abstractions/IDragVisualProvider.cs
+++ b/Lattice.UI.DragDrop/Abstractions/IDragVisualProvider.cs
@@ -6,26 +6,62 @@ namespace Lattice.UI.DragDrop.Abstractions;
 /// <summary>
 /// Поставщик визуального представления для перетаскиваемого элемента.
 /// </summary>
+/// <remarks>
+/// <para>
+/// Интерфейс предоставляет абстракцию для создания и управления визуальными
+/// представлениями элементов при операции перетаскивания.
+/// </para>
+/// <para>
+/// Реализации могут предоставлять различные стили визуального представления:
+/// от простого клонирования оригинального элемента до сложных анимированных представлений.
+/// </para>
+/// </remarks>
 public interface IDragVisualProvider
 {
    /// <summary>
-    /// Создает визуальное представление для перетаскивания.
+    /// Создает визуальное представление для перетаскивания на основе информации о перетаскивании.
    /// </summary>
-    /// <param name="dragInfo">Информация о перетаскивании.</param>
+    /// <param name="dragInfo">Информация о перетаскивании, содержащая данные и метаданные операции.</param>
    /// <param name="initialPosition">Начальная позиция в экранных координатах.</param>
-    /// <returns>Объект, представляющий визуальное отображение.</returns>
-    object CreateDragVisual(DragInfo dragInfo, Point initialPosition);
+    /// <returns>Объект, представляющий визуальное отображение для перетаскивания.</returns>
+    /// <remarks>
+    /// <para>
+    /// Созданный визуальный элемент должен:
+    /// 1. Отображать репрезентативное представление перетаскиваемых данных
+    /// 2. Иметь прозрачный фон или альфа-канал для плавного отображения
+    /// 3. Быть легковесным для обеспечения плавной анимации
+    /// 4. Поддерживать возможность изменения позиции через <see cref="UpdateDragVisualPosition"/>
+    /// </para>
+    /// <para>
+    /// Метод может возвращать null, если визуальное представление не требуется.
+    /// </para>
+    /// </remarks>
+    object? CreateDragVisual(DragInfo dragInfo, Point initialPosition);

    /// <summary>
-    /// Обновляет позицию визуального представления.
+    /// Обновляет позицию визуального представления перетаскивания.
    /// </summary>
-    /// <param name="dragVisual">Визуальное представление.</param>
-    /// <param name="position">Новая позиция.</param>
+    /// <param name="dragVisual">Визуальное представление, созданное методом <see cref="CreateDragVisual"/>.</param>
+    /// <param name="position">Новая позиция в экранных координатах.</param>
+    /// <remarks>
+    /// Метод должен обновить позицию визуального элемента максимально эффективно,
+    /// так как он вызывается часто во время операции перетаскивания.
+    /// </remarks>
    void UpdateDragVisualPosition(object dragVisual, Point position);

    /// <summary>
    /// Освобождает ресурсы визуального представления.
    /// </summary>
-    /// <param name="dragVisual">Визуальное представление.</param>
+    /// <param name="dragVisual">Визуальное представление для освобождения.</param>
+    /// <remarks>
+    /// <para>
+    /// Метод должен освободить все ресурсы, связанные с визуальным представлением,
+    /// включая графические ресурсы, подписки на события и временные данные.
+    /// </para>
+    /// <para>
+    /// Этот метод гарантированно вызывается после завершения операции перетаскивания,
+    /// независимо от её успешности.
+    /// </para>
+    /// </remarks>
    void ReleaseDragVisual(object dragVisual);
 }
--- a/Lattice.UI.DragDrop/Abstractions/IDropVisualAdorner.cs
+++ b/Lattice.UI.DragDrop/Abstractions/IDropVisualAdorner.cs
@@ -6,23 +6,54 @@ namespace Lattice.UI.DragDrop.Abstractions;
 /// <summary>
 /// Визуальный элемент, показывающий обратную связь при наведении на цель сброса.
 /// </summary>
+/// <remarks>
+/// <para>
+/// Интерфейс предоставляет абстракцию для визуальных индикаторов, которые
+/// показывают пользователю возможность сброса данных на целевом элементе.
+/// </para>
+/// <para>
+/// Реализации могут предоставлять различные типы визуальной обратной связи:
+/// подсветку элемента, отображение индикатора позиции, изменение курсора и т.д.
+/// </para>
+/// </remarks>
 public interface IDropVisualAdorner
 {
    /// <summary>
    /// Показывает визуальную обратную связь для цели сброса.
    /// </summary>
-    /// <param name="dropInfo">Информация о сбросе.</param>
-    /// <param name="targetBounds">Границы цели.</param>
+    /// <param name="dropInfo">Информация о потенциальном сбросе, включая данные и позицию.</param>
+    /// <param name="targetBounds">Границы целевого элемента в экранных координатах.</param>
+    /// <remarks>
+    /// <para>
+    /// Метод должен отобразить визуальную обратную связь, соответствующую типу данных
+    /// и контексту сброса. Обратная связь должна явно указывать на возможность
+    /// сброса и ожидаемый эффект (копирование, перемещение и т.д.).
+    /// </para>
+    /// <para>
+    /// Обратная связь должна учитывать свойства <see cref="DropInfo.ShowVisualFeedback"/>
+    /// и <see cref="DropInfo.VisualFeedbackData"/> для кастомизации отображения.
+    /// </para>
+    /// </remarks>
    void Show(DropInfo dropInfo, Rect targetBounds);

    /// <summary>
    /// Обновляет позицию и состояние визуальной обратной связи.
    /// </summary>
-    /// <param name="dropInfo">Информация о сбросе.</param>
+    /// <param name="dropInfo">Текущая информация о сбросе, включая обновленную позицию и состояние.</param>
+    /// <remarks>
+    /// Метод вызывается при каждом перемещении курсора над целью и должен
+    /// обновлять визуальную обратную связь в соответствии с новой позицией
+    /// и состоянием операции.
+    /// </remarks>
    void Update(DropInfo dropInfo);

    /// <summary>
    /// Скрывает визуальную обратную связь.
    /// </summary>
+    /// <remarks>
+    /// Метод должен скрыть и очистить все визуальные элементы обратной связи.
+    /// После вызова этого метода ресурсы могут быть освобождены или переиспользованы
+    /// для следующих операций.
+    /// </remarks>
    void Hide();
 }