118 lines
7.7 KiB
C#
118 lines
7.7 KiB
C#
namespace Lattice.Core.DragDrop.Abstractions;
|
||
|
||
/// <summary>
|
||
/// Определяет контракт для объектов, которые могут принимать сбрасываемые данные
|
||
/// в операции перетаскивания.
|
||
/// </summary>
|
||
/// <remarks>
|
||
/// <para>
|
||
/// Объекты, реализующие этот интерфейс, могут обрабатывать данные, сброшенные
|
||
/// пользователем, и предоставлять визуальную обратную связь во время перетаскивания.
|
||
/// </para>
|
||
/// <para>
|
||
/// Интерфейс поддерживает асинхронные операции и отмену через CancellationToken.
|
||
/// Все методы должны быть потокобезопасными и идемпотентными (многократный вызов
|
||
/// с одинаковыми параметрами должен давать одинаковый результат).
|
||
/// </para>
|
||
/// </remarks>
|
||
public interface IDropTarget
|
||
{
|
||
/// <summary>
|
||
/// Определяет, может ли объект принять сбрасываемые данные.
|
||
/// </summary>
|
||
/// <param name="dropInfo">Информация о потенциальном сбросе.</param>
|
||
/// <param name="cancellationToken">Токен отмены операции.</param>
|
||
/// <returns>
|
||
/// true, если объект может принять данные; в противном случае — false.
|
||
/// </returns>
|
||
/// <remarks>
|
||
/// <para>
|
||
/// Этот метод вызывается, когда перетаскиваемый объект находится над целью.
|
||
/// Реализация должна проверить, совместимы ли данные с целью, и установить
|
||
/// предлагаемые эффекты в свойстве <see cref="Models.DropInfo.SuggestedEffects"/>.
|
||
/// </para>
|
||
/// <para>
|
||
/// Метод может вызываться многократно при перемещении курсора над целью.
|
||
/// Реализация должна быть эффективной и избегать длительных операций.
|
||
/// </para>
|
||
/// <para>
|
||
/// Если метод возвращает false, система не будет вызывать другие методы
|
||
/// для этой цели до тех пор, пока курсор не покинет ее область.
|
||
/// </para>
|
||
/// </remarks>
|
||
Task<bool> CanAcceptDropAsync(Models.DropInfo dropInfo, CancellationToken cancellationToken = default);
|
||
|
||
/// <summary>
|
||
/// Вызывается, когда перетаскиваемый объект перемещается над целью.
|
||
/// </summary>
|
||
/// <param name="dropInfo">Информация о текущем положении перетаскивания.</param>
|
||
/// <param name="cancellationToken">Токен отмены операции.</param>
|
||
/// <returns>Задача, представляющая асинхронную операцию.</returns>
|
||
/// <remarks>
|
||
/// <para>
|
||
/// Этот метод вызывается постоянно, пока пользователь перемещает объект над целью.
|
||
/// Реализация может:
|
||
/// </para>
|
||
/// <list type="bullet">
|
||
/// <item>Обновить визуальную обратную связь (подсветка, изменение курсора)</item>
|
||
/// <item>Вычислить точную позицию сброса (например, между элементами списка)</item>
|
||
/// <item>Уточнить предлагаемые эффекты на основе текущей позиции</item>
|
||
/// <item>Прокрутить содержимое, если цель поддерживает прокрутку</item>
|
||
/// </list>
|
||
/// <para>
|
||
/// Метод должен быть оптимизирован для частого вызова. Длительные операции
|
||
/// должны выполняться асинхронно без блокировки потока.
|
||
/// </para>
|
||
/// </remarks>
|
||
Task OnDragOverAsync(Models.DropInfo dropInfo, CancellationToken cancellationToken = default);
|
||
|
||
/// <summary>
|
||
/// Вызывается, когда пользователь сбрасывает данные на цель.
|
||
/// </summary>
|
||
/// <param name="dropInfo">Информация о сбросе, включая данные и позицию.</param>
|
||
/// <param name="cancellationToken">Токен отмены операции.</param>
|
||
/// <returns>Задача, представляющая асинхронную операцию.</returns>
|
||
/// <remarks>
|
||
/// <para>
|
||
/// Этот метод вызывается, когда пользователь отпускает кнопку мыши над целью.
|
||
/// Реализация должна обработать принятие данных и выполнить соответствующее действие:
|
||
/// </para>
|
||
/// <list type="bullet">
|
||
/// <item>Добавить данные в коллекцию (для копирования)</item>
|
||
/// <item>Переместить данные (при поддержке перемещения)</item>
|
||
/// <item>Создать ссылку на данные</item>
|
||
/// <item>Выполнить пользовательскую логику обработки</item>
|
||
/// </list>
|
||
/// <para>
|
||
/// После успешной обработки данных следует вызвать <see cref="Models.DropInfo.MarkAsHandled()"/>,
|
||
/// чтобы указать системе, что операция обработана и дополнительная обработка не требуется.
|
||
/// </para>
|
||
/// <para>
|
||
/// Если операция завершилась успешно, система уведомит источник через
|
||
/// <see cref="IDragSource.OnDragCompletedAsync"/> с соответствующими эффектами.
|
||
/// </para>
|
||
/// </remarks>
|
||
Task OnDropAsync(Models.DropInfo dropInfo, CancellationToken cancellationToken = default);
|
||
|
||
/// <summary>
|
||
/// Вызывается, когда перетаскиваемый объект покидает область цели.
|
||
/// </summary>
|
||
/// <param name="cancellationToken">Токен отмены операции.</param>
|
||
/// <returns>Задача, представляющая асинхронную операцию.</returns>
|
||
/// <remarks>
|
||
/// <para>
|
||
/// Этот метод вызывается, когда пользователь перемещает объект за пределы цели.
|
||
/// Реализация должна:
|
||
/// </para>
|
||
/// <list type="bullet">
|
||
/// <item>Очистить любую визуальную обратную связь, установленную ранее</item>
|
||
/// <item>Сбросить временное состояние, связанное с операцией</item>
|
||
/// <item>Освободить ресурсы, выделенные для предварительного просмотра</item>
|
||
/// </list>
|
||
/// <para>
|
||
/// Метод гарантированно вызывается после любого успешного или неуспешного
|
||
/// вызова <see cref="OnDragOverAsync"/>, если курсор покидает область цели.
|
||
/// </para>
|
||
/// </remarks>
|
||
Task OnDragLeaveAsync(CancellationToken cancellationToken = default);
|
||
} |