Lattice/Lattice.UI.Docking/Abstractions/IDockDragDropService.cs

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;
    }
}