Переработаны методы.

2026-01-25 02:37:16 +03:00
parent a6ee6fcb36
commit be12154262
17 changed files with 897 additions and 1116 deletions
--- a/Lattice.Core.DragDrop/Services/IDragDropService.cs
+++ b/Lattice.Core.DragDrop/Services/IDragDropService.cs
@@ -8,33 +8,51 @@ public interface IDragDropService : IDisposable
    #region Свойства

    /// <summary>
-    /// Активна ли операция перетаскивания.
+    /// Получает значение, указывающее, активна ли операция перетаскивания.
    /// </summary>
+    /// <value>true, если операция перетаскивания активна; в противном случае — false.</value>
    bool IsDragActive { get; }

    /// <summary>
-    /// Информация о текущей операции.
+    /// Получает информацию о текущей операции перетаскивания.
    /// </summary>
+    /// <value>
+    /// Объект <see cref="Models.DragInfo"/>, содержащий данные текущей операции,
+    /// или null, если операция не активна.
+    /// </value>
    Models.DragInfo? CurrentDragInfo { get; }

    /// <summary>
-    /// Текущая цель сброса.
+    /// Получает текущую цель сброса.
    /// </summary>
+    /// <value>
+    /// Объект <see cref="Abstractions.IDropTarget"/>, над которым находится курсор,
+    /// или null, если курсор не над зарегистрированной целью.
+    /// </value>
    Abstractions.IDropTarget? CurrentDropTarget { get; }

    /// <summary>
-    /// Порог начала перетаскивания в пикселях.
+    /// Получает или задает порог начала перетаскивания в пикселях.
    /// </summary>
+    /// <value>
+    /// Минимальное расстояние, которое должен пройти курсор мыши, чтобы начать операцию перетаскивания.
+    /// Значение по умолчанию: <see cref="Constants.DragDropConstants.DefaultDragThreshold"/>.
+    /// </value>
    double DragStartThreshold { get; set; }

    /// <summary>
-    /// Включены ли асинхронные операции.
+    /// Получает или задает значение, указывающее, включены ли асинхронные операции.
    /// </summary>
+    /// <value>true, если асинхронные операции включены; в противном случае — false.</value>
    bool EnableAsyncOperations { get; set; }

    /// <summary>
-    /// Максимальное время ожидания асинхронной операции (мс).
+    /// Получает или задает максимальное время ожидания асинхронной операции в миллисекундах.
    /// </summary>
+    /// <value>
+    /// Время ожидания в миллисекундах. Значение 0 или меньше означает отсутствие таймаута.
+    /// Значение по умолчанию: <see cref="Constants.DragDropConstants.DefaultAsyncTimeout"/>.
+    /// </value>
    int AsyncOperationTimeout { get; set; }

    #endregion
@@ -42,32 +60,32 @@ public interface IDragDropService : IDisposable
    #region События

    /// <summary>
-    /// Событие начала операции перетаскивания.
+    /// Происходит при начале операции перетаскивания.
    /// </summary>
    event EventHandler<DragStartedEventArgs> DragStarted;

    /// <summary>
-    /// Событие обновления позиции перетаскивания.
+    /// Происходит при обновлении позиции перетаскивания.
    /// </summary>
    event EventHandler<DragUpdatedEventArgs> DragUpdated;

    /// <summary>
-    /// Событие изменения цели сброса.
+    /// Происходит при изменении цели сброса.
    /// </summary>
    event EventHandler<DropTargetChangedEventArgs> DropTargetChanged;

    /// <summary>
-    /// Событие завершения операции перетаскивания.
+    /// Происходит при завершении операции перетаскивания.
    /// </summary>
    event EventHandler<DragCompletedEventArgs> DragCompleted;

    /// <summary>
-    /// Событие отмены операции перетаскивания.
+    /// Происходит при отмене операции перетаскивания.
    /// </summary>
    event EventHandler<DragCancelledEventArgs> DragCancelled;

    /// <summary>
-    /// Событие ошибки в операции перетаскивания.
+    /// Происходит при возникновении ошибки в операции перетаскивания.
    /// </summary>
    event EventHandler<DragDropErrorEventArgs> ErrorOccurred;

@@ -76,23 +94,39 @@ public interface IDragDropService : IDisposable
    #region Регистрация целей сброса

    /// <summary>
-    /// Регистрирует цель сброса.
+    /// Регистрирует цель сброса в системе.
    /// </summary>
+    /// <param name="target">Цель сброса для регистрации.</param>
+    /// <param name="bounds">Границы области цели в координатах экрана.</param>
+    /// <param name="priority">Приоритет цели (высшие значения обрабатываются первыми).</param>
+    /// <param name="group">Имя группы для групповой отмены регистрации.</param>
+    /// <returns>Уникальный идентификатор зарегистрированной цели.</returns>
+    /// <exception cref="ArgumentNullException">Выбрасывается, когда <paramref name="target"/> равен null.</exception>
+    /// <exception cref="ObjectDisposedException">Выбрасывается, если сервис был удален.</exception>
    string RegisterDropTarget(Abstractions.IDropTarget target, Geometry.Rect bounds, int priority = 0, string? group = null);

    /// <summary>
    /// Обновляет границы цели сброса.
    /// </summary>
+    /// <param name="id">Идентификатор цели сброса.</param>
+    /// <param name="bounds">Новые границы области цели.</param>
+    /// <returns>true, если границы успешно обновлены; в противном случае — false.</returns>
+    /// <exception cref="ObjectDisposedException">Выбрасывается, если сервис был удален.</exception>
    bool UpdateDropTargetBounds(string id, Geometry.Rect bounds);

    /// <summary>
    /// Отменяет регистрацию цели сброса.
    /// </summary>
+    /// <param name="id">Идентификатор цели сброса.</param>
+    /// <returns>true, если цель успешно удалена; в противном случае — false.</returns>
+    /// <exception cref="ObjectDisposedException">Выбрасывается, если сервис был удален.</exception>
    bool UnregisterDropTarget(string id);

    /// <summary>
-    /// Отменяет регистрацию всех целей в группе.
+    /// Отменяет регистрацию всех целей сброса в указанной группе.
    /// </summary>
+    /// <param name="group">Имя группы для удаления.</param>
+    /// <exception cref="ObjectDisposedException">Выбрасывается, если сервис был удален.</exception>
    void UnregisterDropTargetsInGroup(string group);

    #endregion
@@ -100,23 +134,54 @@ public interface IDragDropService : IDisposable
    #region Асинхронные операции

    /// <summary>
-    /// Начинает операцию перетаскивания (асинхронно).
+    /// Начинает операцию перетаскивания из указанной позиции.
    /// </summary>
+    /// <param name="source">Источник данных для перетаскивания.</param>
+    /// <param name="startPosition">Начальная позиция операции в координатах экрана.</param>
+    /// <returns>
+    /// Задача, представляющая асинхронную операцию. Результат содержит true, если операция успешно начата;
+    /// в противном случае — false.
+    /// </returns>
+    /// <exception cref="ArgumentNullException">Выбрасывается, когда <paramref name="source"/> равен null.</exception>
+    /// <exception cref="ObjectDisposedException">Выбрасывается, если сервис был удален.</exception>
+    /// <remarks>
+    /// Этот метод следует вызывать в ответ на событие нажатия кнопки мыши или начала жеста перетаскивания.
+    /// </remarks>
    Task<bool> StartDragAsync(Abstractions.IDragSource source, Geometry.Point startPosition);

    /// <summary>
-    /// Обновляет позицию перетаскивания (асинхронно).
+    /// Обновляет позицию текущей операции перетаскивания.
    /// </summary>
+    /// <param name="position">Новая позиция курсора в координатах экрана.</param>
+    /// <returns>Задача, представляющая асинхронную операцию.</returns>
+    /// <exception cref="ObjectDisposedException">Выбрасывается, если сервис был удален.</exception>
+    /// <remarks>
+    /// Этот метод следует вызывать при каждом перемещении мыши во время операции перетаскивания.
+    /// </remarks>
    Task UpdateDragAsync(Geometry.Point position);

    /// <summary>
-    /// Завершает операцию перетаскивания (асинхронно).
+    /// Завершает текущую операцию перетаскивания в указанной позиции.
    /// </summary>
+    /// <param name="position">Позиция завершения операции в координатах экрана.</param>
+    /// <returns>
+    /// Задача, представляющая асинхронную операцию. Результат содержит эффекты, примененные при завершении операции.
+    /// </returns>
+    /// <exception cref="ObjectDisposedException">Выбрасывается, если сервис был удален.</exception>
+    /// <remarks>
+    /// Этот метод следует вызывать при отпускании кнопки мыши или завершении жеста перетаскивания.
+    /// </remarks>
    Task<Enums.DragDropEffects> EndDragAsync(Geometry.Point position);

    /// <summary>
-    /// Отменяет операцию перетаскивания (асинхронно).
+    /// Отменяет текущую операцию перетаскивания.
    /// </summary>
+    /// <returns>Задача, представляющая асинхронную операцию.</returns>
+    /// <exception cref="ObjectDisposedException">Выбрасывается, если сервис был удален.</exception>
+    /// <remarks>
+    /// Этот метод следует вызывать при отмене операции пользователем (например, нажатием клавиши Escape)
+    /// или при возникновении ошибки.
+    /// </remarks>
    Task CancelDragAsync();

    #endregion
@@ -124,27 +189,52 @@ public interface IDragDropService : IDisposable
    #region Утилиты

    /// <summary>
-    /// Очищает все зарегистрированные цели.
+    /// Очищает все зарегистрированные цели сброса.
    /// </summary>
+    /// <exception cref="ObjectDisposedException">Выбрасывается, если сервис был удален.</exception>
    void ClearAllDropTargets();

    /// <summary>
-    /// Получает статистику использования.
+    /// Получает статистику использования системы перетаскивания.
    /// </summary>
+    /// <returns>Объект <see cref="DragDropStats"/> со статистикой использования.</returns>
    DragDropStats GetStats();

    #endregion
 }

 /// <summary>
-/// Статистика использования Drag & Drop.
+/// Содержит статистику использования системы перетаскивания.
 /// </summary>
 public class DragDropStats
 {
+    /// <summary>
+    /// Получает или задает общее количество операций перетаскивания.
+    /// </summary>
    public int TotalDragOperations { get; set; }
+
+    /// <summary>
+    /// Получает или задает количество успешных сбросов.
+    /// </summary>
    public int SuccessfulDrops { get; set; }
+
+    /// <summary>
+    /// Получает или задает количество отмененных операций.
+    /// </summary>
    public int CancelledOperations { get; set; }
+
+    /// <summary>
+    /// Получает или задает количество ошибок.
+    /// </summary>
    public int ErrorCount { get; set; }
+
+    /// <summary>
+    /// Получает или задает количество зарегистрированных целей сброса.
+    /// </summary>
    public int RegisteredTargets { get; set; }
+
+    /// <summary>
+    /// Получает или задает среднее время операции перетаскивания.
+    /// </summary>
    public TimeSpan AverageOperationTime { get; set; }
 }