Lattice/Lattice.Core.DragDrop/Services/EventArgs/DragEventArgs.cs

using Lattice.Core.DragDrop.Models;
using Lattice.Core.Geometry;

namespace Lattice.Core.DragDrop.Services;

/// <summary>
/// Предоставляет базовые данные для событий перетаскивания.
/// </summary>
/// <remarks>
/// Этот класс содержит общие свойства, которые используются в большинстве событий
/// системы перетаскивания. Является базовым классом для специализированных событий.
/// </remarks>
public abstract class DragEventArgs : EventArgs
{
    /// <summary>
    /// Получает информацию о текущей операции перетаскивания.
    /// </summary>
    /// <value>
    /// Объект <see cref="DragInfo"/>, содержащий данные, эффекты и метаданные операции.
    /// Всегда возвращает актуальную информацию на момент возникновения события.
    /// </value>
    public DragInfo DragInfo { get; }

    /// <summary>
    /// Получает текущую позицию курсора в координатах экрана.
    /// </summary>
    /// <value>
    /// Точка, представляющая положение курсора мыши в момент события.
    /// Используется для точного позиционирования и визуальной обратной связи.
    /// </value>
    public Point Position { get; }

    /// <summary>
    /// Инициализирует новый экземпляр класса <see cref="DragEventArgs"/>.
    /// </summary>
    /// <param name="dragInfo">Информация о перетаскивании.</param>
    /// <param name="position">Текущая позиция курсора.</param>
    /// <exception cref="ArgumentNullException">
    /// Выбрасывается, когда <paramref name="dragInfo"/> равен null.
    /// </exception>
    protected DragEventArgs(DragInfo dragInfo, Point position)
    {
        DragInfo = dragInfo ?? throw new ArgumentNullException(nameof(dragInfo));
        Position = position;
    }
}

/// <summary>
/// Предоставляет данные для события начала перетаскивания.
/// </summary>
/// <remarks>
/// Возникает, когда пользователь начинает операцию перетаскивания.
/// Это первое событие в жизненном цикле операции.
/// </remarks>
public sealed class DragStartedEventArgs : DragEventArgs
{
    /// <summary>
    /// Инициализирует новый экземпляр класса <see cref="DragStartedEventArgs"/>.
    /// </summary>
    /// <param name="dragInfo">Информация о перетаскивании.</param>
    /// <param name="position">Начальная позиция перетаскивания.</param>
    public DragStartedEventArgs(DragInfo dragInfo, Point position)
        : base(dragInfo, position)
    {
    }
}

/// <summary>
/// Предоставляет данные для события обновления позиции перетаскивания.
/// </summary>
/// <remarks>
/// Возникает при каждом перемещении курсора во время операции перетаскивания.
/// Может вызываться многократно с высокой частотой, поэтому обработчики
/// должны быть оптимизированы для производительности.
/// </remarks>
public sealed class DragUpdatedEventArgs : DragEventArgs
{
    /// <summary>
    /// Инициализирует новый экземпляр класса <see cref="DragUpdatedEventArgs"/>.
    /// </summary>
    /// <param name="dragInfo">Информация о перетаскивании.</param>
    /// <param name="position">Текущая позиция курсора.</param>
    public DragUpdatedEventArgs(DragInfo dragInfo, Point position)
        : base(dragInfo, position)
    {
    }
}

/// <summary>
/// Предоставляет данные для события завершения перетаскивания.
/// </summary>
/// <remarks>
/// Возникает, когда пользователь завершает операцию перетаскивания
/// (отпускает кнопку мыши над целью или вне области сброса).
/// Содержит информацию о примененных эффектах и результатах операции.
/// </remarks>
public sealed class DragCompletedEventArgs : DragEventArgs
{
    /// <summary>
    /// Получает эффекты, примененные при завершении операции.
    /// </summary>
    /// <value>
    /// Комбинация флагов <see cref="Enums.DragDropEffects"/>, указывающая,
    /// как были обработаны данные (копирование, перемещение и т.д.).
    /// </value>
    public Enums.DragDropEffects Effects { get; }

    /// <summary>
    /// Инициализирует новый экземпляр класса <see cref="DragCompletedEventArgs"/>.
    /// </summary>
    /// <param name="dragInfo">Информация о перетаскивании.</param>
    /// <param name="position">Позиция завершения операции.</param>
    /// <param name="effects">Примененные эффекты перетаскивания.</param>
    public DragCompletedEventArgs(DragInfo dragInfo, Point position, Enums.DragDropEffects effects)
        : base(dragInfo, position)
    {
        Effects = effects;
    }
}

/// <summary>
/// Предоставляет данные для события отмены перетаскивания.
/// </summary>
/// <remarks>
/// Возникает, когда операция перетаскивания была отменена пользователем
/// (например, нажатием клавиши Escape) или системой (например, при ошибке).
/// После этого события система возвращается в исходное состояние.
/// </remarks>
public sealed class DragCancelledEventArgs : DragEventArgs
{
    /// <summary>
    /// Инициализирует новый экземпляр класса <see cref="DragCancelledEventArgs"/>.
    /// </summary>
    /// <param name="dragInfo">Информация о перетаскивании.</param>
    /// <param name="position">Позиция в момент отмены.</param>
    public DragCancelledEventArgs(DragInfo dragInfo, Point position)
        : base(dragInfo, position)
    {
    }
}

/// <summary>
/// Предоставляет данные для события изменения цели сброса.
/// </summary>
/// <remarks>
/// Возникает, когда курсор перемещается с одной цели сброса на другую
/// или покидает область всех целей. Позволяет обновлять визуальную
/// обратную связь при изменении контекста сброса.
/// </remarks>
public sealed class DropTargetChangedEventArgs : DragEventArgs
{
    /// <summary>
    /// Получает новую цель сброса, над которой находится курсор.
    /// </summary>
    /// <value>
    /// Объект <see cref="Abstractions.IDropTarget"/>, готовый принять данные,
    /// или null, если курсор покинул область всех целей.
    /// </value>
    public Abstractions.IDropTarget? Target { get; }

    /// <summary>
    /// Получает границы новой цели сброса.
    /// </summary>
    /// <value>
    /// Прямоугольник, определяющий область цели в координатах экрана.
    /// Может использоваться для точного позиционирования визуальной обратной связи.
    /// </value>
    public Rect TargetBounds { get; }

    /// <summary>
    /// Инициализирует новый экземпляр класса <see cref="DropTargetChangedEventArgs"/>.
    /// </summary>
    /// <param name="dragInfo">Информация о перетаскивании.</param>
    /// <param name="position">Текущая позиция курсора.</param>
    /// <param name="target">Новая цель сброса.</param>
    /// <param name="targetBounds">Границы цели сброса.</param>
    public DropTargetChangedEventArgs(DragInfo dragInfo, Point position, Abstractions.IDropTarget? target, Rect targetBounds)
        : base(dragInfo, position)
    {
        Target = target;
        TargetBounds = targetBounds;
    }
}

/// <summary>
/// Предоставляет данные для события ошибки в операции перетаскивания.
/// </summary>
/// <remarks>
/// Возникает при возникновении исключения в любом из компонентов
/// системы перетаскивания. Позволяет централизованно обрабатывать ошибки
/// и предоставлять пользователю информацию о проблемах.
/// </remarks>
public sealed class DragDropErrorEventArgs : EventArgs
{
    /// <summary>
    /// Получает исключение, вызвавшее ошибку.
    /// </summary>
    /// <value>
    /// Объект <see cref="Exception"/>, содержащий информацию об ошибке.
    /// Может быть любого типа, в зависимости от источника ошибки.
    /// </value>
    public Exception Exception { get; }

    /// <summary>
    /// Получает название операции, во время которой произошла ошибка.
    /// </summary>
    /// <value>
    /// Строка, идентифицирующая операцию (например, "StartDragAsync",
    /// "OnDropAsync", "UpdateDropTargetBounds").
    /// </value>
    public string Operation { get; }

    /// <summary>
    /// Получает контекст, в котором произошла ошибка.
    /// </summary>
    /// <value>
    /// Объект, содержащий дополнительную информацию о контексте ошибки,
    /// или null, если контекст недоступен.
    /// </value>
    public object? Context { get; }

    /// <summary>
    /// Инициализирует новый экземпляр класса <see cref="DragDropErrorEventArgs"/>.
    /// </summary>
    /// <param name="exception">Исключение, вызвавшее ошибку.</param>
    /// <param name="operation">Название операции.</param>
    /// <param name="context">Контекст ошибки.</param>
    /// <exception cref="ArgumentNullException">
    /// Выбрасывается, когда <paramref name="exception"/> или <paramref name="operation"/> равны null.
    /// </exception>
    public DragDropErrorEventArgs(Exception exception, string operation, object? context = null)
    {
        Exception = exception ?? throw new ArgumentNullException(nameof(exception));
        Operation = operation ?? throw new ArgumentNullException(nameof(operation));
        Context = context;
    }
}