DragAndDrop core

2026-01-18 16:33:35 +03:00
parent 9ea82af329
commit 79bdd8bc62
229 changed files with 21214 additions and 2494 deletions
--- a/Lattice.UI.Docking/Abstractions/IDockDragDropService.cs
+++ b/Lattice.UI.Docking/Abstractions/IDockDragDropService.cs
@@ -0,0 +1,256 @@
+namespace Lattice.UI.Docking.Abstractions;
+
+/// <summary>
+/// Предоставляет сервис для операций перетаскивания в UI-слое док-системы.
+/// Абстрагирует платформенно-зависимую логику перетаскивания и обеспечивает
+/// единый интерфейс для управления операциями drag-and-drop.
+/// </summary>
+/// <remarks>
+/// Этот интерфейс служит мостом между базовым менеджером перетаскивания из Core
+/// и UI-контролами, добавляя визуальную обратную связь и обработку событий,
+/// специфичных для пользовательского интерфейса.
+/// </remarks>
+public interface IDockDragDropService
+{
+    /// <summary>
+    /// Начинает операцию перетаскивания для указанного элемента.
+    /// </summary>
+    /// <param name="element">UI-контрол, который инициирует перетаскивание.</param>
+    /// <param name="dragInfo">
+    /// Информация о перетаскивании, содержащая данные и параметры операции.
+    /// </param>
+    /// <exception cref="ArgumentNullException">
+    /// Выбрасывается, если <paramref name="element"/> или <paramref name="dragInfo"/> равны null.
+    /// </exception>
+    /// <remarks>
+    /// Этот метод должен создавать визуальное представление перетаскиваемого элемента
+    /// и инициировать отслеживание перемещения мыши.
+    /// </remarks>
+    void StartDrag(IDockControl element, Core.DragDrop.Models.DragInfo dragInfo);
+
+    /// <summary>
+    /// Обновляет позицию текущей операции перетаскивания.
+    /// </summary>
+    /// <param name="x">Новая координата X курсора в экранных координатах.</param>
+    /// <param name="y">Новая координата Y курсора в экранных координатах.</param>
+    /// <remarks>
+    /// Вызывается при каждом перемещении мыши во время операции перетаскивания.
+    /// Должен обновлять позицию визуального представления и проверять возможные цели сброса.
+    /// </remarks>
+    void UpdateDrag(double x, double y);
+
+    /// <summary>
+    /// Завершает текущую операцию перетаскивания в указанной позиции.
+    /// </summary>
+    /// <param name="x">Координата X завершения перетаскивания.</param>
+    /// <param name="y">Координата Y завершения перетаскивания.</param>
+    /// <remarks>
+    /// Выполняет сброс данных на текущую цель (если она есть) и очищает ресурсы,
+    /// выделенные для операции перетаскивания.
+    /// </remarks>
+    void EndDrag(double x, double y);
+
+    /// <summary>
+    /// Отменяет текущую операцию перетаскивания.
+    /// </summary>
+    /// <remarks>
+    /// Вызывается при нажатии клавиши Escape или других действиях, приводящих к отмене.
+    /// Должен восстанавливать исходное состояние элементов и очищать ресурсы.
+    /// </remarks>
+    void CancelDrag();
+
+    /// <summary>
+    /// Показывает визуальную подсказку о возможной позиции сброса.
+    /// </summary>
+    /// <param name="element">UI-контрол, для которого показывается подсказка.</param>
+    /// <param name="position">Предполагаемая позиция сброса.</param>
+    /// <remarks>
+    /// Используется для визуальной обратной связи, чтобы пользователь видел,
+    /// куда будет помещен элемент при отпускании кнопки мыши.
+    /// </remarks>
+    void ShowDropHint(IDockControl element, Models.DropPosition position);
+
+    /// <summary>
+    /// Скрывает текущую визуальную подсказку о сбросе.
+    /// </summary>
+    /// <remarks>
+    /// Вызывается, когда курсор покидает допустимую область сброса
+    /// или операция перетаскивания завершается.
+    /// </remarks>
+    void HideDropHint();
+
+    /// <summary>
+    /// Событие, возникающее при начале операции перетаскивания.
+    /// </summary>
+    event EventHandler<DragStartedEventArgs> DragStarted;
+
+    /// <summary>
+    /// Событие, возникающее при обновлении позиции перетаскивания.
+    /// </summary>
+    event EventHandler<DragUpdatedEventArgs> DragUpdated;
+
+    /// <summary>
+    /// Событие, возникающее при завершении операции перетаскивания.
+    /// </summary>
+    event EventHandler<DragCompletedEventArgs> DragCompleted;
+
+    /// <summary>
+    /// Событие, возникающее при отмене операции перетаскивания.
+    /// </summary>
+    event EventHandler DragCancelled;
+}
+
+/// <summary>
+/// Предоставляет данные для события начала перетаскивания.
+/// </summary>
+public class DragStartedEventArgs : EventArgs
+{
+    /// <summary>
+    /// Получает UI-контрол, который инициировал перетаскивание.
+    /// </summary>
+    /// <value>
+    /// Экземпляр <see cref="IDockControl"/>, представляющий источник перетаскивания.
+    /// Может быть null, если перетаскивание инициировано не из UI-элемента.
+    /// </value>
+    public IDockControl? Source { get; }
+
+    /// <summary>
+    /// Получает информацию о перетаскивании.
+    /// </summary>
+    /// <value>
+    /// Экземпляр <see cref="Core.DragDrop.Models.DragInfo"/> с данными перетаскивания.
+    /// </value>
+    public Core.DragDrop.Models.DragInfo DragInfo { get; }
+
+    /// <summary>
+    /// Инициализирует новый экземпляр класса <see cref="DragStartedEventArgs"/>.
+    /// </summary>
+    /// <param name="source">Источник перетаскивания.</param>
+    /// <param name="dragInfo">Информация о перетаскивании.</param>
+    public DragStartedEventArgs(IDockControl? source, Core.DragDrop.Models.DragInfo dragInfo)
+    {
+        Source = source;
+        DragInfo = dragInfo;
+    }
+}
+
+/// <summary>
+/// Предоставляет данные для события обновления перетаскивания.
+/// </summary>
+public class DragUpdatedEventArgs : EventArgs
+{
+    /// <summary>
+    /// Получает UI-контрол, который инициировал перетаскивание.
+    /// </summary>
+    /// <value>
+    /// Экземпляр <see cref="IDockControl"/>, представляющий источник перетаскивания.
+    /// </value>
+    public IDockControl? Source { get; }
+
+    /// <summary>
+    /// Получает текущую координату X курсора.
+    /// </summary>
+    /// <value>
+    /// Координата X в экранных координатах.
+    /// </value>
+    public double X { get; }
+
+    /// <summary>
+    /// Получает текущую координату Y курсора.
+    /// </summary>
+    /// <value>
+    /// Координата Y в экранных координатах.
+    /// </value>
+    public double Y { get; }
+
+    /// <summary>
+    /// Получает информацию о перетаскивании.
+    /// </summary>
+    /// <value>
+    /// Экземпляр <see cref="Core.DragDrop.Models.DragInfo"/> с текущими данными перетаскивания.
+    /// </value>
+    public Core.DragDrop.Models.DragInfo DragInfo { get; }
+
+    /// <summary>
+    /// Инициализирует новый экземпляр класса <see cref="DragUpdatedEventArgs"/>.
+    /// </summary>
+    /// <param name="source">Источник перетаскивания.</param>
+    /// <param name="x">Текущая координата X.</param>
+    /// <param name="y">Текущая координата Y.</param>
+    /// <param name="dragInfo">Информация о перетаскивании.</param>
+    public DragUpdatedEventArgs(IDockControl? source, double x, double y, Core.DragDrop.Models.DragInfo dragInfo)
+    {
+        Source = source;
+        X = x;
+        Y = y;
+        DragInfo = dragInfo;
+    }
+}
+
+/// <summary>
+/// Предоставляет данные для события завершения перетаскивания.
+/// </summary>
+public class DragCompletedEventArgs : EventArgs
+{
+    /// <summary>
+    /// Получает UI-контрол, который инициировал перетаскивание.
+    /// </summary>
+    /// <value>
+    /// Экземпляр <see cref="IDockControl"/>, представляющий источник перетаскивания.
+    /// Может быть null, если операция была инициирована не из UI.
+    /// </value>
+    public IDockControl? Source { get; }
+
+    /// <summary>
+    /// Получает UI-контрол, на который был выполнен сброс.
+    /// </summary>
+    /// <value>
+    /// Экземпляр <see cref="IDockControl"/>, представляющий цель сброса.
+    /// Может быть null, если сброс был выполнен вне допустимой области.
+    /// </value>
+    public IDockControl? Target { get; }
+
+    /// <summary>
+    /// Получает позицию сброса относительно целевого элемента.
+    /// </summary>
+    /// <value>
+    /// Значение перечисления <see cref="DropPosition"/>, указывающее позицию сброса.
+    /// </value>
+    public Models.DropPosition DropPosition { get; }
+
+    /// <summary>
+    /// Получает информацию о перетаскивании.
+    /// </summary>
+    /// <value>
+    /// Экземпляр <see cref="Core.DragDrop.Models.DragInfo"/> с данными завершенной операции.
+    /// Может быть null, если операция была отменена.
+    /// </value>
+    public Core.DragDrop.Models.DragInfo? DragInfo { get; }
+
+    /// <summary>
+    /// Получает значение, указывающее успешность операции сброса.
+    /// </summary>
+    /// <value>
+    /// true, если данные были успешно сброшены на цель; false, если операция была отменена
+    /// или сброс не был выполнен.
+    /// </value>
+    public bool Success { get; }
+
+    /// <summary>
+    /// Инициализирует новый экземпляр класса <see cref="DragCompletedEventArgs"/>.
+    /// </summary>
+    /// <param name="source">Источник перетаскивания.</param>
+    /// <param name="target">Цель сброса.</param>
+    /// <param name="dropPosition">Позиция сброса.</param>
+    /// <param name="dragInfo">Информация о перетаскивании.</param>
+    /// <param name="success">Признак успешности операции.</param>
+    public DragCompletedEventArgs(IDockControl? source, IDockControl? target,
+        Models.DropPosition dropPosition, Core.DragDrop.Models.DragInfo? dragInfo, bool success)
+    {
+        Source = source;
+        Target = target;
+        DropPosition = dropPosition;
+        DragInfo = dragInfo;
+        Success = success;
+    }
+}