240 lines
12 KiB
C#
240 lines
12 KiB
C#
namespace Lattice.Core.DragDrop.Services;
|
||
|
||
/// <summary>
|
||
/// Предоставляет централизованный сервис для управления операциями перетаскивания.
|
||
/// </summary>
|
||
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
|
||
|
||
#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;
|
||
|
||
#endregion
|
||
|
||
#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
|
||
|
||
#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
|
||
|
||
#region Утилиты
|
||
|
||
/// <summary>
|
||
/// Очищает все зарегистрированные цели сброса.
|
||
/// </summary>
|
||
/// <exception cref="ObjectDisposedException">Выбрасывается, если сервис был удален.</exception>
|
||
void ClearAllDropTargets();
|
||
|
||
/// <summary>
|
||
/// Получает статистику использования системы перетаскивания.
|
||
/// </summary>
|
||
/// <returns>Объект <see cref="DragDropStats"/> со статистикой использования.</returns>
|
||
DragDropStats GetStats();
|
||
|
||
#endregion
|
||
}
|
||
|
||
/// <summary>
|
||
/// Содержит статистику использования системы перетаскивания.
|
||
/// </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; }
|
||
} |